kicad-doc-devs team mailing list archive

["paulvdh@xxxxxxxxxxxxxxxx" <paulvdh@xxxxxxxxxxxxxxxx>]

On Sat, 26 Sep 2020 15:25:18 -0400
Jon Evans <jon@xxxxxxxxxxxxx> wrote:

> Hi docs team,
> 
> 6.0 Feature Freeze is around the corner.  Once that hits, I plan on
> investing some time in updating the docs, especially for features I've been
> involved with developing.
> 
> Are there any big architectural changes to the docs coming that I should
> wait for before starting this effort?  For example, I'm not sure if we're
> going to try to switch to Asciidoctor, etc.
> 
> One architectural thing I wanted to ask is:
> 
> Currently we have "single page per application" documentation, plus the
> "getting started" page.
> While one page per application works well for all the "accessories" like
> GerbView, PCB Calculator, etc, I think it's not the right paradigm anymore
> for the core of KiCad.
> 
> What I would suggest is to instead split up the documentation by "task
> areas":
> 
> 1) Getting Started
> 2) Creating Schematics
> 3) Creating PCBs
> 4) Creating and Managing Libraries
> 5) Configuring and Customizing KiCad
> 
> Any thoughts about something like this?
> 
> -Jon

Some time ago, (Search: 2019-04-18, oops, that long ago) I joined the docs team for a serious atempt to update the "Getting started with KiCad" guide, as I had a lot of benefit from it, and later noticed it was out of date for quite some time. Then it got stranded for a whole lot of complicated reasons.

For a "single page manuals" the cheatsheet is in the center of the Venn diagram. Some improvement to this would be to make it fit both on both on A4 and on letter formats. It's also missing some very handy keys, such as the [Ins] to repeat (with auto numbering) and it still mentions the old method of generating a netlist file instead of [F8].

The "creating ..." titles look like chapters for the "Getting started with KiCad".
There should be different sets of manuals. A "Getting started" may skip a lot of stuff, and just mention the minimal needed to get a feel of KiCad and get from a schematic to a routed PCB in a single afternoon.

Then there are reference manuals, which should document each funktion in detail.

Rene Poschl (and some others) have also written a lot of "how to ..." guides in the FAQ section of the users forum:
https://forum.kicad.info/c/faq
Maybe parts of these should be ported to manuals, or else, adding a link in manuals to this FAQ for information on various topics would be a good idea.

Those are (a small portion of) my thoughts.