kicad-doc-devs team mailing list archive

[Heitor <heitorpbittencourt@xxxxxxxxx>]

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

Attachment: pgprNAoRVX793.pgp
Description: OpenPGP digital signature