kicad-developers team mailing list archive

[Jon Evans <jon@xxxxxxxxxxxxx>]

> THE MAIN PROBLEM ARE THE OUTDATED DOCUMENTS!
> NOT THE WAY THEY ARE DISTRIBUTED.

One reason the documents are outdated is that they are hard to contribute
to.
They are hard to contribute to in part because they use a toolchain that
only works well on Linux, and many of our users who might feel like
contributing use Windows or Mac.
Simplifying the toolchain would enable easy contribution from any platform.

Also, as I mentioned before, the docs and the source code will generally
never be in sync, and there is not much point in trying to make them be in
sync.  This would just needlessly delay releases.  It is better to have a
"rolling" 6.x documentation separate from the 6.0.x bugfix releases of code
(but see below, I don't mind that some distributions "require" a matching
6.0.x release of the docs).

Separately, gettext/po4a is not the best tool for managing translation of
long-form documentation.  Yes, we have a "working" system, but it doesn't
work very well.  Documentation should be translated in large chunks, for
example by reading an entire paragraph or section and then translating it
into the target language with an understanding of the full context.  Doing
it in small chunks as is done today will not result in great translations
as the source (English) documents are updated and rewritten.

I don't have a specific proposal for a different system yet (this problem
is well-solved in the commercial world using commercial tooling, but I'm
not sure the best path for open-source and free tooling), but I do maintain
that we should be looking at improving this system.

> Do not try to "solve" things were distributions already have a process
> for and established rules for that.

If the distributions "need" 6.0.1 tagged documentation because of their
rules, that is fine.  There is no reason to stop providing that.  It is
just obviously not the best way to provide the documentation to users who
have Internet access, so I am talking about ideas to provide more updated
documentation to users that can make use of it.

-Jon

On Thu, Jan 20, 2022 at 10:59 AM Carsten Schoenert <c.schoenert@xxxxxxxxxxx>
wrote:

> Hi,
>
> Am 19.01.22 um 23:18 schrieb Eeli Kaikkonen:
>
> > I don't understand why this discussion is so difficult to understand.
>
> sorry but I don't understand what problem you are trying to solve!
> There is no problem within the Linux world and their distros to provide
> packaged documentation, there is no need to develop another new way for
> distributing documentation.
>
> > I agree with Jon and don't see any problem for distros. As far as I
> > can see the point is that the documentation package version shouldn't
> > be logically dependent on the KiCad packages or vice versa. You can
> > have package kicad-v6.0-documentation version, say, 20222001 [date],
> > can't you? You don't have to give it the version number 6.0.x. If a
> > git tag is needed for technical reasons, let's have automatic tagging
> > which adds a tag each day.
>
> To use the words from Marco...
>
> "Are you serious?"
>
> I'm getting a bit disappointed because I become the feeling that you are
> somehow ignorant about the arguments of at least two main packagers of
> KiCad within Linux. And I really think that you want to solve problems
> on the wrong corner.
>
> THE MAIN PROBLEM ARE THE OUTDATED DOCUMENTS!
> NOT THE WAY THEY ARE DISTRIBUTED.
>
> So it's better to think about how the documentation can be updated and
> how a ongoing process can be introduced to make contributions easier
> with a low barrier for one time contributors.
>
> And as Marco did explain, we need to fix the tools if there is something
> missed at the end. Be friendly to the distributions, please do not try
> to ignore them. They are part of the FOSS ecosystem KiCad is depending on.
> Do not try to "solve" things were distributions already have a process
> for and established rules for that.
>
> I stop now reading any new post on this topic.
>
> --
> Regards
> Carsten
>
> _______________________________________________
> Mailing list: https://launchpad.net/~kicad-developers
> Post to     : kicad-developers@xxxxxxxxxxxxxxxxxxx
> Unsubscribe : https://launchpad.net/~kicad-developers
> More help   : https://help.launchpad.net/ListHelp
>