kicad-doc-devs team mailing list archive

[Jon Evans <jon@xxxxxxxxxxxxx>]

Oh and one thing I forgot: The "Getting started" section would also include
the basic introduction to the KiCad project manager and how to create
projects.

On Sat, Sep 26, 2020 at 4:11 PM 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.
>
> -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
>>
>