kicad-doc-devs team mailing list archive

[Константин Барановский <baranovskiykonstantin@xxxxxxxxx>]

It would be great if the documentation will be separate to two parts:
offline and online.
"Offline" docs describe tools (menu items), settings, warnings and
restrictions. These docs *have to* be installed with KiCad and be available
for users at any time.
"Online" docs may be organized as a wiki. The KiCad Wiki may contain as the
large articles like "Getting started", "Creating schematic/pcb/library" as
the small articles like "Tracing diff pairs", "Creating pads with custom
shapes" etc.
Articles may be created by developers to describe new features they bring.
Many themes from the kicad forum have some useful solutions that may be
converted to the wiki articles.
I think KiCad must have a wiki.

пн, 28 сент. 2020 г. в 08:48, 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
>
> --
> 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
>