kicad-doc-devs team mailing list archive

[Jon Evans <jon@xxxxxxxxxxxxx>]

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
>