> 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.schoen...@t-online.de> 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@lists.launchpad.net > Unsubscribe : https://launchpad.net/~kicad-developers > More help : https://help.launchpad.net/ListHelp >
_______________________________________________ Mailing list: https://launchpad.net/~kicad-developers Post to : kicad-developers@lists.launchpad.net Unsubscribe : https://launchpad.net/~kicad-developers More help : https://help.launchpad.net/ListHelp
