kicad-doc-devs team mailing list archive

[Ian McInerney <Ian.S.McInerney@xxxxxxxx>]

I agree that the one binary per chapter is probably going to be less useful
now. For example, it would make the most sense to describe all annotation
systems in one place, and we now have geographical reannotation and
back-annotation in Pcbnew - so annotation is in both programs.

-Ian

On Sun, 27 Sep 2020, 01:15 Jon Evans, <jon@xxxxxxxxxxxxx> wrote:

> I agree that it would be nice to have some "official" guides as well.
>
> I am not proposing converting the manuals to guides, just that:
>
> - The manuals can be arranged in a way that puts emphasis on things people
> are more likely to need
> - Having one manual per binary (eeschema vs pcbnew, etc) may not be the
> right "arrangement of chapters"
>
> -Jon
>
> On Sat, Sep 26, 2020 at 7:43 PM Heitor <heitorpbittencourt@xxxxxxxxx>
> wrote:
>
>> On Sat, 26 Sep 2020 16:11:40 -0400
>> Jon Evans <jon@xxxxxxxxxxxxx> wrote:
>>
>> > To take my idea a bit further:
>> >
>> > If we did this, I would suggest we change a bit what the Getting
>> > Started section means.
>> > Instead of a "cheat sheet" introduction to all aspects of KiCad, it
>> > would just be a more general introduction:
>> >
>> > - Installing and upgrading
>> > - General user interface paradigms
>> > - Key vocabulary
>> > - Where to find help outside the manual
>> >
>> > Then, the "creating schematics" section would include both the basics
>> > in the beginning and more advanced techniques at the end.
>> >
>> > The manuals should still be manuals (i.e. not tutorials) but I think
>> > it's still OK to start with the most common workflows and talk about
>> > advanced or uncommon workflows at the end of a section.
>>
>> I also support this idea of two different "types" of documentation:
>> manuals and guides.
>>
>> A manual should have a detailed description of every
>> function/menu/option of every component of KiCad. It is not supposed to
>> be read from beginning to end, but instead it should be consulted when
>> the user is not sure of something.
>>
>> A guide, on the other hand, is more like a tutorial and should be self
>> contained, direct to the point, and as short as possible. For example:
>> - a guide on library management
>> - a guide on spice simulations
>> - a guide on creating/improving the component library and submitting a
>>   PR on GitHub
>> - a getting started guide, covering how to capture a schematic, layout
>>   the board and export the files to manufacture.
>> - a guide on plugins
>> - the ones that Jon suggested, and etc
>>
>> Some of those guides are already in the user's forums. It would be nice
>> to move them to the official docs, so there would be translations to
>> other languages as well.
>>
>> There are a few issues on GitLab about rewriting the docs:
>> - https://gitlab.com/kicad/services/kicad-doc/-/issues/618
>> - https://gitlab.com/kicad/services/kicad-doc/-/issues/394
>>
>> --
>> Heitor
>> --
>> Mailing list: https://launchpad.net/~kicad-doc-devs
>> Post to     : kicad-doc-devs@xxxxxxxxxxxxxxxxxxx
>> Unsubscribe : https://launchpad.net/~kicad-doc-devs
>> More help   : https://help.launchpad.net/ListHelp
>>
> --
> Mailing list: https://launchpad.net/~kicad-doc-devs
> Post to     : kicad-doc-devs@xxxxxxxxxxxxxxxxxxx
> Unsubscribe : https://launchpad.net/~kicad-doc-devs
> More help   : https://help.launchpad.net/ListHelp
>