kicad-doc-devs team mailing list archive

[Jon Evans <jon@xxxxxxxxxxxxx>]

Good suggestions, Marco!

Regarding translations:

1) If we move chunks of text from one doc to another, is it easy to keep
the translations updated?

2) For the V6 documentation effort, is it best to do things gradually while
translators work in the background, or having a "documentation freeze"
after which all the translations happen?


The context help idea is a good one, I'm not sure if there is an issue for
this on GitLab yet.  We may be able to add this in a future KiCad version.

Best,
Jon

On Sun, Sep 27, 2020 at 5:47 PM Marco Ciampa <ciampix@xxxxxxxxxx> wrote:

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