kicad-developers team mailing list archive

[Carsten Schoenert <c.schoenert@xxxxxxxxxxx>]

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.

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

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

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

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

--
Regards
Carsten