← Back to team overview

kicad-developers team mailing list archive

Re: V6 documentation

 

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


Follow ups

References