kicad-doc-devs team mailing list archive

[Marco Ciampa <ciampix@xxxxxxxxxx>]

On Sun, Sep 27, 2020 at 05:51:28PM -0400, Jon Evans wrote:
> 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?

After merging the master document together you can also merge the
translations together (the .po files) with the help of the gettext
specialized command msgmerge. That must be done manually for each
language but luckily, just once.

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

I think that when working on such important changes it is better to stop
translations for a while (so a "translation freeze" must be announced)
and to ask translators commit their work, whatever state their works are,
before committing those strucural changes to avoid frustrations and
resent (it has happened in the past, unfortunately) of the translators.

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

For KiCad 7 at least... yes I'll add an issue on GitLab...thanks for the
suggestion!

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

-- 

Saluton,
Marco Ciampa