kicad-doc-devs team mailing list archive

[Jon Evans <jon@xxxxxxxxxxxxx>]

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.

-Jon

On Sat, Sep 26, 2020 at 4:07 PM paulvdh@xxxxxxxxxxxxxxxx <
paulvdh@xxxxxxxxxxxxxxxx> wrote:

> 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.
>
>
> --
> 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
>