kicad-developers team mailing list archive

[Jon Evans <jon@xxxxxxxxxxxxx>]

On Wed, Jan 19, 2022 at 1:05 PM Carsten Schoenert <c.schoenert@xxxxxxxxxxx>
wrote:

> [ I'm on this list, no need to address me dedicated. ]
>

My email client does this automatically, but if it bothers you I removed it
manually :)

>
> Am 19.01.22 um 18:45 schrieb Jon Evans:
>
> > I think you misunderstand.  We currently have three rolling releases on
> > docs.kicad.org <http://docs.kicad.org>: V5, V6, and master (nightly).
> > We will continue adding new "rolling release" builds for every major
> > release version.
>
> I think I have understand you. :)
>
> But for me "rolling release" and "stable release" isn't something that
> is working well together as it simply doesn't fit together per definition.
>

It does if you consider that the way KiCad is developed, we have no
requirement (and in practice, a guarantee against) the documentation being
up-to-date to a certain code tag at the time the code tag is made.

The way the project currently works, the docs will generally *never* be
complete for a given tag at the time that tag is made.
Maybe this can be different in the future if we get way more volunteers to
write documentation.


>
> [cut off]
> I stand on my opinion, I'm not convinced that most of the things you
> suggested is the way to go.
>
> > The price is that the average Linux user will get 6.0.1 tagged docs
> > instead of latest V6 docs (and so forth) and won't necessarily think to
> > check for updated ones.
>
> That's the idea behind packages that using a tagged version. I haven't
> seen any professional software is doing that you suggest.
> And the typical experienced Linux user isn't behaving like Windows user.
>

On the other hand, I have seen a lot of professional software going to
online-only documentation.

I think the "typical" Linux user wants up-to-date documentation and has
Internet access.  The kind who does not have Internet access, or cares a
lot about how the documentation is packaged, is not the "mass market" Linux
user.  KiCad is not some software targeted at some narrow segment of Linux
users: probably most of our users are on Windows.


>
> > You are confusing rolling release of binary packages/applications with
> > rolling release of documentation -- they are entirely different in my
> mind.
>
> No, I don't.
> Doing constantly bug fixing for current stable releases of KiCad doesn't
> exclude doing the same for improving the (stable) documentation
> independently from the current development branch.
>

We agree on this!  But, the documentation and the code are decoupled as I
said above, so the time at which code 6.0.2 is tagged might not be the same
time as we want to update the 6.x documentation.


>
> I'm not a native English speaker and I'm not really able to help on this
> part effectively, and also I have given up long time ago trying
> contributing to the KiCad documentation for various reasons.
>
> The main devs are free to do and decide whatever they think is the right
> thing and way for KiCad. I simple don't see why it would be really
> helpful for the users what you are proposing. In my eyes is dropping
> existing formats a loss of well working and usable support.
>

I believe part of the reason we have trouble getting people to help write
the documentation is because the build process is tricky (it is only easy
on Linux; I've spent some time trying to make it run on Windows and Mac but
given up as a waste of time).  We have a lot of active and engaged users on
Windows and Mac who basically cannot contribute to the documentation
because they can't easily build and test it locally.

One thing we could do that would help this is to change the build process
so that the main build is only HTML, and PDF build is an optional extra
generated from the HTML (that can be enabled by a CI job for packaging).
Another thing would be to change the translation system from the existing
gettext/po system (which is not very well suited to long-form text) to a
manual translation system.

-Jon