kicad-doc-devs team mailing list archive

[Marco Ciampa <ciampix@xxxxxxxxxx>]

On Sun, Sep 27, 2020 at 08:20:39AM -0400, Wayne Stambaugh wrote:
> All of this sounds good to me.  It going to be a lot of work.  I am
> planning to document all of the new features I added during V6 including
> the new file formats.  I'm not sure were the file format documents
> should be part of the regular documentation or if it belongs somewhere else.
> 
> - Wayne
> 

I agree to all the suggestion made here, and I have a lot more. But...

1) my advice: babi steps. All these changes are huge and I doubt that we
can make them all for the exit of the KiCad 6.0 version.

I would suggest to try one (big) thing at a time, in that way letting
translators keep up with the documentations changes.

One example can be merging some application manuals into one, trying to
save most of the translations in the process.

2) before migrating to asciidoctor I would consider:

  a) improving the cmake scripts that are now far from perfect, and in
  the same time adapting them to be compatible with both asciidoc
  and asciidoctor

  b) at least upgrade to the last versions of asciidoc
  (>9.0 with its due port to python 3) and po4a raising the
  minimum version number.

3) I too would separate the "introduction" and "tutorial" manuals from
the "reference" manuals, but those separations can be just "sections" of
one big documentation file.  In that way we can enable references between
those sections in terms of hyperlinks that would just work in whichever
format we decide to compile our documentation body to (html, pdf, epub).

4) I would also enable some sort of "context" help. 

The function that is present in many programs nowadays (one for all, the
GIMP, see: https://docs.gimp.org/2.10/en/gimp-help-context.html) when you
press the F1 for manual index and Shift-F1 for the "context" help.

When you press the "context help" key combination, the cursor turns into
a question mark "?" and then if you press the mouse button on to a
function in the program, the manual window opens directly into that
specific part of the reference manual describing that function.

That function can easily be obtained making those program commands /
functions / windows refer to specific chapter titles and specific IDs in
the documentation. Making IDs in the documentation is really easy as it
is already done to make internal hyperlinks. See:

https://asciidoc.org/userguide.html#X41


--

Saluton,
Marco Ciampa