kicad-developers team mailing list archive

[Jon Evans <jon@xxxxxxxxxxxxx>]

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

> Hello Jon,
>
> Am 19.01.22 um 17:38 schrieb Jon Evans:
> > Carsten,
> >
> > There is no reason to remove the ability to package docs offline, I just
> > don't think it should be a focus of the project.
>
> here start to disagree.
> In my eyes the offline bundled and created documentation IS a strong
> service the project should always have a focus on.
>
> > The majority of users will be served better by keeping a "rolling
> > release" online at docs.kicad.org <http://docs.kicad.org> (with a
> > download button, ideally).
>
> I disagree again, I know several users of KiCad which don't follow a
> rolling release of KiCad valid reasons and even don't update to a new
> main version because the current one ore more big projects is critical.
> Professional users typically don't have the time to follow rolling
> releases as this is lost and unpaid time for them. It's easier to live
> with the know problems and to work around them. And once a new version
> is out and the time has come projects can do and will do the version
> update.
>
> A rolling release only of the online documentation is also counter
> productive in such a case, as it would be probably mostly wrong for the
> old used version potentially.
>

I think you misunderstand.  We currently have three rolling releases on
docs.kicad.org: V5, V6, and master (nightly).
We will continue adding new "rolling release" builds for every major
release version.

So, the V6 documentation is rolling-released to the web, but the nightly is
also (and is separate).

This means that we will continue improving the V6 documentation over the
coming year, and *also* can start documenting the V7 features without any
conflict.

The point I was making is that someone who installs 6.0.1 today should get
the latest V6 branch docs (not the latest master branch) ideally.
Anyone with internet access should be able to get the latest docs, not the
docs at the 6.0.1 tag.


>
> >  > It absolutely doesn't hurt to build completely offline usable
> > documentation.
> >
> > It does hurt the way we do it today, for the following reasons:
> >
> > 1) We currently support multiple formats, which makes the build system
> > and formatting changes complicated
>
> So what?
> Isn't it exact the purpose of the build system to solve all these
> problems for the users?
>

No, a build system can't resolve the fact that publishing to multiple
formats creates a "lowest common denominator" situation, unless a human is
manually converting between formats in a smart way.


> And currently there isn't something special format built, at least I
> don't see why HTML, PDF and ePUB diff that much between, except the way
> they are created.
> If you see a problem within the supporting of the formats the tooling
> for creating needs improvements! But as long nowadays developers (not
> KiCad devs!) thinking that every problem needs to be solved by some
> Node.JS stuff the "solutions" going worse every day.
>

I am not sure what you mean here, but HTML/CSS is the easiest path to a
nice-looking, accessible, searchable and cross-linked set of documentation
today.  There is lots of tooling out there for accomplishing this goal.


>
> > 2) We currently tie the documentation version together with the
> > application version, and don't have good workflows for "rolling release"
> > of documentation for Linux distros that use separate packages.
>
> There is no need to support some sort of rolling release for tagged
> versions, sorry,


Yes there is, see above for my reasoning.


> I don't get what goal is wanted to archive here. The
> problem isn't the rolling release if you want to name it that way. There
> is a toolchain that is building the various formats and this stays the
> same basically.
>

The current toolchain holds us back from improving the HTML/CSS
documentation.


>
> The current problem is simply the current outdated base which requires a
> lot of work to get this updated. Evolving the documentation for the
> current dev branch is something different from supporting the current
> stable released version.
>

Answered above


>
> > 3) The application itself doesn't handle the situation where offline
> > docs are missing very gracefully, or note to users that when offline
> > docs are present that they are probably outdated.
>
> The KiCad application can't do anything about that circumstance. It
> simply just can start some external resource. So it's the responsibility
> of that resource to handle that. Is see no problem in adding some header
> or similar into the current documentation that is saying that the most
> recent version this document can be found there and there.
>
> > What I would propose to improve the situation is:
> >
> > 1) Drop all formats except HTML.  HTML is perfectly fine as an offline
> > format, and this allows us to make improvements to the build workflow
> > and the layout/style of the docs without worrying about doing so in a
> > way that also works for PDF.  If you really want a PDF, you can render
> > it from HTML pages anyway.
>
> Why?
> My father isn't able to handle this for the most of us simple task. I
> don't think such a step is really user friendly.
> I was e.g. happy to have the documentation readable on my EBook reader
> as this was the most suitable device for me to read it.
>
> I see no real costs to provide al these formats as these are really
> common formats.
>

See above for the cost.


>
> > 2) Change the application to gracefully redirect to the online docs if
> > offline docs are missing
>
> Agreed.
>
> > 3) Make a better "offline docs" build that adds the warning about docs
> > being out-of-date.  Have packagers use this if they want to generate
> > docs packages, and maybe make it easy for anyone to download these from
> > the website.
>
> Shouldn't be that difficult as this is mostly the current state.
>
> > 4) Stop tagging the kicad-docs repo with every KiCad code release.
> > Instead, continue the new practice we have started of maintaining major
> > release branches for the docs (V5, V6, etc) and have packagers start
> > packaging the tip of these branches.  I.e. the Ubuntu package for
> > kicad-docs will update every time something is pushed to the V6 branch
> > as long as V6 is the stable release, and so on.
>
> Here I disagree again, most of the Linux distribution have some tooling
> created to collect all the required tarballs or tags as they need always
> some upstream tarball that is used for everything that is created later.
>
> Tags doesn't cost some price and are "just" a maker for a single commit.
>

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.

You are confusing rolling release of binary packages/applications with
rolling release of documentation -- they are entirely different in my mind.


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