Re: [Kicad-developers] V6 documentation

[Nick Østergaard]

Hi Franck,

This should be  superceeded by:
https://dev-docs.kicad.org/en/file-formats/

Nick

On Wed, 19 Jan 2022 at 19:41, Franck Bourdonnec  wrote:
>
>
> About doc, this one seems good but bazaar, no revision, no datestamp ?
>
> Is it maintained ?
>
>
> bazaar.launchpad.net/~stambaughw/kicad/doc-read-only/download/head:/1115%4016bec504-3128-0410-b3e8-8e38c2123bca:trunk%252Fkicad-doc%252Fdoc%252Fhelp%252Ffile_formats%252Ffile_formats.pdf/file_formats.pdf
>
>
> ___
> 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

Re: [Kicad-developers] V6 documentation

[Eeli Kaikkonen]

It looks like this is a sensitive topic, and I now understand the
packagers feel pressure and that they aren't appreciated enough. That
wasn't my intention and I didn't want to hint or imply anything
negative towards anyone. On the contrary, I know packaging isn't easy
(I have looked at the packaging systems and given up) and appreciate
the work.

There seems to be more than one subjects going on, packaging is only
one. The more fundamental is the need or lack of need for offline
documentation, and if there is need, how is that solved. This also
seems to be a sensitive topic. Personally I don't see why
documentation should be packaged at all for distros if it can be
downloaded anyway.

I mentioned PCM, not because I would think it would be the best
solution, but just for brainstorming (however, this topic seems to be
too sensitive for brainstorming). It would just be a natural way to
download KiCad documentation because other content is downloaded with
it, too, and it would be readily available to the end users. An extra
benefit would be that it would automatically go to a location known to
KiCad, so if KiCad tries to find local documentation, it would be in
the right place.

Eeli Kaikkonen

On Thu, Jan 20, 2022 at 5:59 PM Carsten Schoenert
 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

Re: [Kicad-developers] V6 documentation

[Jon Evans]

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

Re: [Kicad-developers] V6 documentation

[Carsten Schoenert]

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

Re: [Kicad-developers] V6 documentation

[Marco Ciampa]

On Wed, Jan 19, 2022 at 06:37:46PM -0500, Steven A. Falco wrote:
> On 1/19/22 05:18 PM, Eeli Kaikkonen wrote:
> > On Wed, Jan 19, 2022 at 9:13 PM Steven A. Falco  
> > wrote:
> > 
> > > It would still be helpful if the doc repo could be tagged at the same 
> > > point that everything else is tagged, because every single Fedora package 
> > > needs a correct version in its name.  For example, it would be very 
> > > strange (perhaps "illegal") to package something called the 6.0.1 doc 
> > > that came from some random SHA in an untagged tree.
> > 
> > I don't understand why this discussion is so difficult to understand.
> > 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.
> 
> > I don't think the discussion is difficult to understand.  

> But Fedora's process doesn't map into what you have just proposed.

Not just Fedora's but nearly any other distro do not work in that way...

-- 

Saluton,
Marco Ciampa

___
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

Re: [Kicad-developers] V6 documentation

[Marco Ciampa]

On Wed, Jan 19, 2022 at 02:09:08PM -0500, Jon Evans wrote:
> 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.

Ok, following your reasoning let's drop support for MacOS and Linux and
focus only on Windows since most of the users are there... see? There is
something you are missing here...

[...]

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

Ok let's improve this instead! And since the strings are .po files. Why
not use an online service to support translations like transifex,
weblate, zanata, pootle, crowdin, etc. with an online CI integration
support it should be much less difficult...

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

That would be a HUGE mistake. PDF made from HTML are just horrible and
unusable. The same for epub (that I use and love).

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

Are you serious? That would even a bigger mistake!

That would make the translation process completely unmanageable... just
imagine to have to read and compare manually hundred of pages to see what
changed in the original... impossible!

--

Saluton,
Marco Ciampa

___
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

Re: [Kicad-developers] V6 documentation

[Marco Ciampa]

On Wed, Jan 19, 2022 at 11:38:02AM -0500, Jon Evans wrote:
> 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.
> The majority of users will be served better by keeping a "rolling release"
> online at docs.kicad.org (with a download button, ideally).
> 
> > 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

It is not. It depends on the tool you use. If (when) we switch to
asciidoctor, creating pdfs is straightforward and, in the near future,
also will be epubs.

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

If there are rolling releases of source packages, similarly, then there
will be rolling releases of docs. I do not see the problem here.
 
> 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.

That is a bug. You should report it as usual.

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

Dropping something because you don't use it is a short-sighted
decision... please don't.

> 2) Change the application to gracefully redirect to the online docs if
> offline docs are missing

OK this I agree with.

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

That potentially can clash with the package distribution of the local
system. Instead it could be useful to have one more option: local
installed docs. This is an example:

User customizable docs access. Please select what do you prefer (you can
always change it later):

- Local system docs
- Local user docs
- On-line docs

local user docs CAN be updated directly from on-line zips, and the
process can be automated. In this way it won't be interferences with the
system packages...

Imagine a warning at Kicad start:

"It seems that there are newer (more updated) docs on the kicad site than
the version you installed system-wide. Do you want to download and
install them locally and set the help option preference to access the
local docs instead of the (older) system installed? Yes/no"

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

We cannot interfere with distro packaging policies. Every distro have a
general politics for packaging and won't change that only for the kicad
package. Obviously others, more general, packaging systems can be better
taylored to follow our needs like, for instance, flatpacks...

-- 

Saluton,
Marco Ciampa

___
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

Re: [Kicad-developers] V6 documentation

[Steven A. Falco]

On 1/19/22 05:18 PM, Eeli Kaikkonen wrote:

On Wed, Jan 19, 2022 at 9:13 PM Steven A. Falco  wrote:


It would still be helpful if the doc repo could be tagged at the same point that 
everything else is tagged, because every single Fedora package needs a correct version in 
its name.  For example, it would be very strange (perhaps "illegal") to package 
something called the 6.0.1 doc that came from some random SHA in an untagged tree.


I don't understand why this discussion is so difficult to understand.
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.


I don't think the discussion is difficult to understand.  But Fedora's process 
doesn't map into what you have just proposed.

Currently, there is one single script (a "spec" file) that controls the build 
of all the components of KiCad on Fedora.  This includes the executable programs, 
libraries, and docs.

There is nothing automatic about the process.  When a new build is needed, I download the 
tar files based on a tag, upload them to a lookaside cache called "dist-git", 
and then I queue a build on Fedora's koji system.  Once that completes, I download the 
resulting artifacts, test them, and then submit the artifacts for further testing by the 
larger community.  Eventually, those artifacts get blessed and go into the distribution 
system as new packages.

It is all a very manual process, and I only do it when some significant event 
occurs, like when a new tag is placed.  Also, it takes time - the review 
process generally takes a full week, so daily package updates to the docs are 
out of the question.

So, there is no point to tagging the docs on a daily basis.  And since that tag 
wouldn't agree with the one on the KiCad program, it would have to be a 
separately maintained thing, which would double my work.  And it would still 
only be built occasionally - not every day, because like I said, it is a very 
manual process, and takes a lot longer than a day to complete.

Personally I'd like to see things stay the way they are as far as the tagging 
goes.  The docs would be tagged at the same time and with the same tag as 
everything else.  Yes, they might soon be out of date, which is why I suggested 
that the code default to using the on-line copy, whenever it is available, and 
only use the off-line copy when there was no connection.  That would cover most 
users who have an internet connection.

But that is not essential.  As Jon said, if someone chooses not to install the 
doc package, then they'd get the on-line version.

Perhaps the best thing would be to completely eliminate building the docs on 
Fedora.  That way, nobody could install them, and they'd always get the on-line 
version.

Steve

___
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

Re: [Kicad-developers] V6 documentation

[Eeli Kaikkonen]

On Wed, Jan 19, 2022 at 9:13 PM Steven A. Falco  wrote:

> It would still be helpful if the doc repo could be tagged at the same point 
> that everything else is tagged, because every single Fedora package needs a 
> correct version in its name.  For example, it would be very strange (perhaps 
> "illegal") to package something called the 6.0.1 doc that came from some 
> random SHA in an untagged tree.

I don't understand why this discussion is so difficult to understand.
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.

Eeli Kaikkonen

___
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

Re: [Kicad-developers] V6 documentation

[Jon Evans]

> Here's a wild idea: why not make the documentation bundle(s) downloadable
with the PCM?

I'm not sure that would be worth the extra effort, since it wouldn't help
the people that can't use online documentation because Internet access is
restricted.

Yes, you could download a PCM package and then install it via a USB stick
or whatever (but probably not in a secure environment), but you could also
download the docs website.

-Jon

On Wed, Jan 19, 2022 at 5:03 PM Eeli Kaikkonen 
wrote:

> On Wed, Jan 19, 2022 at 6:38 PM Jon Evans  wrote:
> >
> > What I would propose to improve the situation is:
>
> Here's a wild idea: why not make the documentation bundle(s)
> downloadable with the PCM?
>
> Eeli Kaikkonen
>
> ___
> 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

Re: [Kicad-developers] V6 documentation

[Eeli Kaikkonen]

On Wed, Jan 19, 2022 at 6:38 PM Jon Evans  wrote:
>
> What I would propose to improve the situation is:

Here's a wild idea: why not make the documentation bundle(s)
downloadable with the PCM?

Eeli Kaikkonen

___
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

Re: [Kicad-developers] V6 documentation

[Steven A. Falco]

On 1/19/22 02:16 PM, Jon Evans wrote:


On Wed, Jan 19, 2022 at 2:12 PM Steven A. Falco mailto:stevenfa...@gmail.com>> wrote:


Not to put words in your mouth, but it sounds like the code will be changed 
so that when someone clicks on the Help menu, they will get the on-line 
version, if possible.
And only if the on-line version cannot be accessed, the code would then 
automatically fall back to the off-line (local) version.  Do I have the 
proposal correct?  If so, I like it.


Yes, something like that.  But, instead it could be to use the offline version 
if present, and fall back to the online version if absent.  Then it would be up 
to the packager to decide whether or not to include the offline docs (I'd 
propose to drop them from the Windows and Mac packages that we provide).


It might also be good to have a warning somewhere, perhaps in the off-line 
version itself, that it is not necessarily current, along with a suggestion to 
go retrieve the on-line version manually.


Yes, I think this is important, just have to figure out how to add it to the 
generated documentation but not the website.


It would still be helpful if the doc repo could be tagged at the same point that 
everything else is tagged, because every single Fedora package needs a correct version in 
its name.  For example, it would be very strange (perhaps "illegal") to package 
something called the 6.0.1 doc that came from some random SHA in an untagged tree.


I am not trying to break any distro's packaging requirements for the sake of 
making people's lives hard, I am just trying to make it so the average KiCad 
user who has access to the online docs finds them first.

Maybe one option would be to not install the documentation package by default 
when the user selects the main kicad package.  That way, a user who just 
installs kicad will get the online docs redirect, and one who cares about 
offline docs can manually install the extra package?


That is how things are packaged right now, both for Fedora nightlies and for 
Fedora downstream (official) packages.  We build three packages:

1) main program + all libraries except 3d (because it is huge)

2) docs

3) 3d library

So nobody has to install the docs.  As long as the off-line docs indicate that 
there may be more current on-line docs, that should be fine.

Steve


___
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

Re: [Kicad-developers] V6 documentation

[Jon Evans]

On Wed, Jan 19, 2022 at 2:12 PM Steven A. Falco 
wrote:

>
> Not to put words in your mouth, but it sounds like the code will be
> changed so that when someone clicks on the Help menu, they will get the
> on-line version, if possible.
> And only if the on-line version cannot be accessed, the code would then
> automatically fall back to the off-line (local) version.  Do I have the
> proposal correct?  If so, I like it.
>

Yes, something like that.  But, instead it could be to use the offline
version if present, and fall back to the online version if absent.  Then it
would be up to the packager to decide whether or not to include the offline
docs (I'd propose to drop them from the Windows and Mac packages that we
provide).


> It might also be good to have a warning somewhere, perhaps in the off-line
> version itself, that it is not necessarily current, along with a suggestion
> to go retrieve the on-line version manually.
>

Yes, I think this is important, just have to figure out how to add it to
the generated documentation but not the website.


>
> It would still be helpful if the doc repo could be tagged at the same
> point that everything else is tagged, because every single Fedora package
> needs a correct version in its name.  For example, it would be very strange
> (perhaps "illegal") to package something called the 6.0.1 doc that came
> from some random SHA in an untagged tree.
>

I am not trying to break any distro's packaging requirements for the sake
of making people's lives hard, I am just trying to make it so the average
KiCad user who has access to the online docs finds them first.

Maybe one option would be to not install the documentation package by
default when the user selects the main kicad package.  That way, a user who
just installs kicad will get the online docs redirect, and one who cares
about offline docs can manually install the extra package?
___
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

Re: [Kicad-developers] V6 documentation

[Steven A. Falco]

On 1/19/22 12:45 PM, Jon Evans wrote:

... snip ...


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.


Not to put words in your mouth, but it sounds like the code will be changed so 
that when someone clicks on the Help menu, they will get the on-line version, 
if possible.

And only if the on-line version cannot be accessed, the code would then 
automatically fall back to the off-line (local) version.  Do I have the 
proposal correct?  If so, I like it.

It might also be good to have a warning somewhere, perhaps in the off-line 
version itself, that it is not necessarily current, along with a suggestion to 
go retrieve the on-line version manually.

It would still be helpful if the doc repo could be tagged at the same point that 
everything else is tagged, because every single Fedora package needs a correct version in 
its name.  For example, it would be very strange (perhaps "illegal") to package 
something called the 6.0.1 doc that came from some random SHA in an untagged tree.

Steve

___
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

[Kicad-developers] V6 documentation

[Jon Evans]

On Wed, Jan 19, 2022 at 1:05 PM Carsten Schoenert 
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 : 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
___
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

Re: [Kicad-developers] V6 documentation

[Franck Bourdonnec]

About doc, this one seems good but bazaar, no revision, no datestamp ?

Is it maintained ?


bazaar.launchpad.net/~stambaughw/kicad/doc-read-only/download/head:/1115%4016bec504-3128-0410-b3e8-8e38c2123bca:trunk%252Fkicad-doc%252Fdoc%252Fhelp%252Ffile_formats%252Ffile_formats.pdf/file_formats.pdf


___
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

Re: [Kicad-developers] V6 documentation

[Carsten Schoenert]

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

Am 19.01.22 um 18:45 schrieb Jon Evans:

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.


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.


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

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.


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.



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

Re: [Kicad-developers] V6 documentation

[Jon Evans]

On Wed, Jan 19, 2022 at 12:37 PM Carsten Schoenert 
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  (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

Re: [Kicad-developers] V6 documentation

[Carsten Schoenert]

Am 19.01.22 um 18:12 schrieb Steven A. Falco:


I don't disagree, but really, we could say that everything is always
outdated - the code, the libs etc.  I have to pick a point in time,
and create packages as of that point - currently that point is when a
new release is tagged.  I.e., it is a manual process - I have to
consciously create the packages, and it then takes a week or so for
the packages to sit in the testing repositories before being released
to general users.  I have no control over that process.


Exactly!

The main part of the Linux distributions are simply not intended to 
build as rolling release.
There is simply no way to "work around" this within the rule set of 
these distributions.


Users that want to follow some nightly and so called releases will need 
to use distribution/flavor A or B or C that can and will support this.


But I haven't seen a serious usage of what Linux DE ever that was build 
on distributions that are using a rolling release model.


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

Re: [Kicad-developers] V6 documentation

[Carsten Schoenert]

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

Re: [Kicad-developers] V6 documentation

[Jon Evans]

The way we have split things up now, the nightly docs are not the
appropriate pairing for the V6 stable release -- they may diverge over time.

I think the vast majority of Linux users also have access to the Internet
and so directing them to the most up-to-date docs is the right move.

I am not saying we should remove any way for people in high-security
offline environments to get documentation, but just that it shouldn't be
the default option.

-Jon

On Wed, Jan 19, 2022 at 12:12 PM Steven A. Falco 
wrote:

> On 1/19/22 12:00 PM, Jon Evans wrote:
> > That just doesn't seem that useful to me.  The fact that Fedora forces
> this process means that Fedora offline docs will always be outdated.
>
> I don't disagree, but really, we could say that everything is always
> outdated - the code, the libs etc.  I have to pick a point in time, and
> create packages as of that point - currently that point is when a new
> release is tagged.  I.e., it is a manual process - I have to consciously
> create the packages, and it then takes a week or so for the packages to sit
> in the testing repositories before being released to general users.  I have
> no control over that process.
>
> > If there is no way to work around it for Fedora, I suggest we develop an
> out-of-band way of delivering offline docs to people (not using the Fedora
> packaging system).
>
> People can always download the nightly docs packages via Copr, which will
> correspond to whatever is in the master branch.  There is no process at the
> moment for nightlies to build from any other branch, although I suppose one
> could be added.
>
> Steve
>
> >
> >
> > On Wed, Jan 19, 2022 at 11:52 AM Steven A. Falco  > wrote:
> >
> > Right now, the downstream (official) Fedora builds depend on a
> single tag for all the components - source code, libraries, and docs.
> >
> > I could substitute a SHA for the docs, but I'd have to hard-code the
> SHA in the "spec file" that controls the build, the same way the tag is
> hard-coded in the spec file.
> >
> > Since all the components are built at the same time from the same
> script, it would not be possible to "update every time something is pushed
> to the V6 branch".  I.e., Fedora builds are not a "rolling release" - they
> are tied to tags.
> >
> >  Steve
> >
> > On 1/19/22 11:38 AM, Jon Evans wrote:
> >  > 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.
> >  > 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).
> >  >
> >  >  > 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
> >  >
> >  > 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.
> >  >
> >  > 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.
> >  >
> >  > 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.
> >  >
> >  > 2) Change the application to gracefully redirect to the online
> docs if offline docs are missing
> >  >
> >  > 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.
> >  >
> >  > 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.
> >  >
> >  > -Jon
> >  >
> >  > On Wed, Jan 19, 2022 at 11:29 AM Carsten Schoenert <
> c.schoen...@t-online.de   c.schoen...@t-online.de >> wrote:
> >  >
> > 

Re: [Kicad-developers] V6 documentation

[Steven A. Falco]

On 1/19/22 12:00 PM, Jon Evans wrote:

That just doesn't seem that useful to me.  The fact that Fedora forces this 
process means that Fedora offline docs will always be outdated.


I don't disagree, but really, we could say that everything is always outdated - 
the code, the libs etc.  I have to pick a point in time, and create packages as 
of that point - currently that point is when a new release is tagged.  I.e., it 
is a manual process - I have to consciously create the packages, and it then 
takes a week or so for the packages to sit in the testing repositories before 
being released to general users.  I have no control over that process.


If there is no way to work around it for Fedora, I suggest we develop an 
out-of-band way of delivering offline docs to people (not using the Fedora 
packaging system).


People can always download the nightly docs packages via Copr, which will 
correspond to whatever is in the master branch.  There is no process at the 
moment for nightlies to build from any other branch, although I suppose one 
could be added.

Steve




On Wed, Jan 19, 2022 at 11:52 AM Steven A. Falco mailto:stevenfa...@gmail.com>> wrote:

Right now, the downstream (official) Fedora builds depend on a single tag 
for all the components - source code, libraries, and docs.

I could substitute a SHA for the docs, but I'd have to hard-code the SHA in the 
"spec file" that controls the build, the same way the tag is hard-coded in the 
spec file.

Since all the components are built at the same time from the same script, it would not be 
possible to "update every time something is pushed to the V6 branch".  I.e., Fedora 
builds are not a "rolling release" - they are tied to tags.

         Steve

On 1/19/22 11:38 AM, Jon Evans wrote:
 > 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.
 > The majority of users will be served better by keeping a "rolling release" online at 
docs.kicad.org  > (with 
a download button, ideally).
 >
 >  > 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
 >
 > 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.
 >
 > 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.
 >
 > 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.
 >
 > 2) Change the application to gracefully redirect to the online docs if 
offline docs are missing
 >
 > 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.
 >
 > 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.
 >
 > -Jon
 >
 > On Wed, Jan 19, 2022 at 11:29 AM Carsten Schoenert mailto:c.schoen...@t-online.de> >> wrote:
 >
 >     Hello,
 >
 >     Am 19.01.22 um 17:21 schrieb Gabriel Staples, 
ElectricRCAircraftGuy.com:
 >     ...
 >      > In other words, please do make "online documentation" only, as it 
allows
 >      > faster updates to it and better consistency,
 >
 >     please don't!
 >     It absolutely doesn't hurt to build completely offline usable
 >     documentation. It works for years without special requirements.
 >
 >     I work often in environments where I have absolutely no access to the
 >     internet, but can use packaged software, so I heavily need offline
 >     documentation to do some sort of productive work.
 >
 >     --
 >     Regards
 >     Carsten
 >
 >     

Re: [Kicad-developers] V6 documentation

[Jon Evans]

That just doesn't seem that useful to me.  The fact that Fedora forces this
process means that Fedora offline docs will always be outdated.

If there is no way to work around it for Fedora, I suggest we develop an
out-of-band way of delivering offline docs to people (not using the Fedora
packaging system).


On Wed, Jan 19, 2022 at 11:52 AM Steven A. Falco 
wrote:

> Right now, the downstream (official) Fedora builds depend on a single tag
> for all the components - source code, libraries, and docs.
>
> I could substitute a SHA for the docs, but I'd have to hard-code the SHA
> in the "spec file" that controls the build, the same way the tag is
> hard-coded in the spec file.
>
> Since all the components are built at the same time from the same script,
> it would not be possible to "update every time something is pushed to the
> V6 branch".  I.e., Fedora builds are not a "rolling release" - they are
> tied to tags.
>
> Steve
>
> On 1/19/22 11:38 AM, Jon Evans wrote:
> > 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.
> > The majority of users will be served better by keeping a "rolling
> release" online at docs.kicad.org  (with a
> download button, ideally).
> >
> >  > 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
> >
> > 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.
> >
> > 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.
> >
> > 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.
> >
> > 2) Change the application to gracefully redirect to the online docs if
> offline docs are missing
> >
> > 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.
> >
> > 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.
> >
> > -Jon
> >
> > On Wed, Jan 19, 2022 at 11:29 AM Carsten Schoenert <
> c.schoen...@t-online.de > wrote:
> >
> > Hello,
> >
> > Am 19.01.22 um 17:21 schrieb Gabriel Staples,
> ElectricRCAircraftGuy.com:
> > ...
> >  > In other words, please do make "online documentation" only, as it
> allows
> >  > faster updates to it and better consistency,
> >
> > please don't!
> > It absolutely doesn't hurt to build completely offline usable
> > documentation. It works for years without special requirements.
> >
> > I work often in environments where I have absolutely no access to the
> > internet, but can use packaged software, so I heavily need offline
> > documentation to do some sort of productive work.
> >
> > --
> > Regards
> > Carsten
> >
> > ___
> > Mailing list: https://launchpad.net/~kicad-developers <
> https://launchpad.net/~kicad-developers>
> > Post to : kicad-developers@lists.launchpad.net  kicad-developers@lists.launchpad.net>
> > Unsubscribe : https://launchpad.net/~kicad-developers <
> https://launchpad.net/~kicad-developers>
> > More help   : https://help.launchpad.net/ListHelp <
> 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
>
>
> ___
> 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
>

Re: [Kicad-developers] V6 documentation

[Steven A. Falco]

Right now, the downstream (official) Fedora builds depend on a single tag for 
all the components - source code, libraries, and docs.

I could substitute a SHA for the docs, but I'd have to hard-code the SHA in the 
"spec file" that controls the build, the same way the tag is hard-coded in the 
spec file.

Since all the components are built at the same time from the same script, it would not be possible 
to "update every time something is pushed to the V6 branch".  I.e., Fedora builds are not 
a "rolling release" - they are tied to tags.

Steve

On 1/19/22 11:38 AM, Jon Evans wrote:

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.
The majority of users will be served better by keeping a "rolling release" online at 
docs.kicad.org  (with a download button, ideally).

 > 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

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.

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.

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.

2) Change the application to gracefully redirect to the online docs if offline 
docs are missing

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.

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.

-Jon

On Wed, Jan 19, 2022 at 11:29 AM Carsten Schoenert mailto:c.schoen...@t-online.de>> wrote:

Hello,

Am 19.01.22 um 17:21 schrieb Gabriel Staples, ElectricRCAircraftGuy.com:
...
 > In other words, please do make "online documentation" only, as it allows
 > faster updates to it and better consistency,

please don't!
It absolutely doesn't hurt to build completely offline usable
documentation. It works for years without special requirements.

I work often in environments where I have absolutely no access to the
internet, but can use packaged software, so I heavily need offline
documentation to do some sort of productive work.

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



___
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

Re: [Kicad-developers] V6 documentation

[Gabriel Staples, ElectricRCAircraftGuy.com]

I think we are saying the same thing? The other parts of what I said were
to ensure it is downloadable for offline use. When I say "online
documentation," I mean:

   1. it is html files viewed from a browser
   2. the most up-to-date version is online and updated rapidly (instantly)
   as new documentation is edited or made
   3. the whole online documentation website is fully downloadable for
   offline use, both as an auto-generated PDF, and as an HTML website, since
   access to the documentation while offline must **never** be done away with.

Thanks!

Gabriel Staples

(sent from my Android)

Le mer. 19 janv. 2022, 9:30 AM, Carsten Schoenert 
a écrit :

> Hello,
>
> Am 19.01.22 um 17:21 schrieb Gabriel Staples, ElectricRCAircraftGuy.com:
> ...
> > In other words, please do make "online documentation" only, as it allows
> > faster updates to it and better consistency,
>
> please don't!
> It absolutely doesn't hurt to build completely offline usable
> documentation. It works for years without special requirements.
>
> I work often in environments where I have absolutely no access to the
> internet, but can use packaged software, so I heavily need offline
> documentation to do some sort of productive work.
>
> --
> 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

Re: [Kicad-developers] V6 documentation

[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.
The majority of users will be served better by keeping a "rolling release"
online at docs.kicad.org (with a download button, ideally).

> 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

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.

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.

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.

2) Change the application to gracefully redirect to the online docs if
offline docs are missing

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.

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.

-Jon

On Wed, Jan 19, 2022 at 11:29 AM Carsten Schoenert 
wrote:

> Hello,
>
> Am 19.01.22 um 17:21 schrieb Gabriel Staples, ElectricRCAircraftGuy.com:
> ...
> > In other words, please do make "online documentation" only, as it allows
> > faster updates to it and better consistency,
>
> please don't!
> It absolutely doesn't hurt to build completely offline usable
> documentation. It works for years without special requirements.
>
> I work often in environments where I have absolutely no access to the
> internet, but can use packaged software, so I heavily need offline
> documentation to do some sort of productive work.
>
> --
> 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

Re: [Kicad-developers] V6 documentation

[Carsten Schoenert]

Hello,

Am 19.01.22 um 17:21 schrieb Gabriel Staples, ElectricRCAircraftGuy.com:
...
In other words, please do make "online documentation" only, as it allows 
faster updates to it and better consistency,


please don't!
It absolutely doesn't hurt to build completely offline usable 
documentation. It works for years without special requirements.


I work often in environments where I have absolutely no access to the 
internet, but can use packaged software, so I heavily need offline 
documentation to do some sort of productive work.


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

Re: [Kicad-developers] V6 documentation

[Gabriel Staples, ElectricRCAircraftGuy.com]

Oh, ok. I agree with this. I'd be fine with downloading the code separate
from the documentation and not packaging them together. The documentation
released separately just needs to clearly state which software version it
goes with is all.

Thanks!

Gabriel Staples

(sent from my Android)

Le mer. 19 janv. 2022, 9:23 AM, Jon Evans  a écrit :

> I am not saying offline documentation isn't important.
>
> I'm saying offline documentation *bundled with a specific KiCad release*
> isn't important.
>
> If someone needs offline documentation, we should make it easy for them to
> obtain the latest "snapshot" of any given doc branch from our website.
> Just bundling a snapshot with the code release will mean that the docs are
> not in sync with the code (because we don't have a team of doc writers who
> keep the docs up-to-date at the same rate that we release code changes)
>
> -Jon
>
> On Wed, Jan 19, 2022 at 11:21 AM Gabriel Staples,
> ElectricRCAircraftGuy.com  wrote:
>
>> > I'm not sure that this is a very important feature in today's world.
>>
>> In many parts of the government, and in some research labs, offline
>> documentation is still **very important** because they block nearly all of
>> the internet. But, a healthy compromise would be to have online
>> documentation only, but to have it downloadable as an html website package
>> so you can still browse it when offline.
>>
>> Also, i can see some rural schools and areas not having good internet and
>> being in trouble if someone like me wants to get the kids excited about
>> KiCad but we can't load the documentation. So, again, it needs to be easily
>> downloadable.
>>
>> In other words, please do make "online documentation" only, as it allows
>> faster updates to it and better consistency, but please do also make the
>> whole documentation site easily downloadable to be viewed in a browser when
>> offline.
>>
>>
>> Thanks!
>>
>> Gabriel Staples
>>
>> (sent from my Android)
>>
>> Le mar. 18 janv. 2022, 11:12 AM, Jon Evans  a écrit :
>>
>>> We have decided to update the online documentation in a rolling fashion,
>>> meaning that new changes go "live" pretty quickly after being approved and
>>> merged.
>>>
>>> The version that is bundled with the application is a snapshot in time
>>> (at the point that software release was made).
>>>
>>> I think moving to an online-only help system is actually a good idea and
>>> I've talked about this before some -- it would also make it easier to
>>> improve the formatting of the documentation, since we would have only one
>>> output format (HTML/CSS) to deal with.
>>>
>>> The main reason to include offline documentation (other than "because
>>> that's how it's always been done with KiCad") is to provide documentation
>>> that is accessible if the user's computer doesn't have an internet
>>> connection.  I'm not sure that this is a very important feature in today's
>>> world.
>>>
>>> -Jon
>>>
>>> On Tue, Jan 18, 2022 at 1:05 PM Tom A.  wrote:
>>>
 I don't have view at all, not really a software engineer so may take a
 bit of spamming with some questions that may be quite obvious to others.

 My first question is why in the software Help section is so dated and
 online version much more up to date? It seems you can access online version
 from the software, so why to include old (probably no more relevant)
 documentation?

 Regards,
 Tomas

 On Tue, 18 Jan 2022, 17:17 Jon Evans,  wrote:

> I don't personally see the point of spamming the list with back and
> forth about setting up Git/Gitlab, installing dependencies, etc.
>
> But, I am not opposed to it if others don't care.
>
> -Jon
>
> On Tue, Jan 18, 2022 at 12:02 PM Marco Ciampa 
> wrote:
>
>> On Tue, Jan 18, 2022 at 09:10:22AM -0500, Jon Evans wrote:
>> > Hi Tomas,
>> >
>> > I've been loosely coordinating documentation updates for V6.  There
>> are not
>> > very many other people working on it.  We'd be happy to have your
>> help.
>> > If you contact me off-list I can help you get set up to make
>> changes and we
>> > can figure out where you'd like to start.
>>
>> I don't want to be rude but I do not understand. This list is almost
>> silent. For sure some docs dev set-up instructions will not hurt
>> anybody
>> and perhaps there is something to learn (I bet I'll learn something
>> anyway ...). So please do not discuss that elsewhere. This list was
>> meant
>> also for this.
>>
>> --
>>
>> Saluton,
>> Marco Ciampa
>>
>> ___
>> 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: 

Re: [Kicad-developers] V6 documentation

[Jon Evans]

I am not saying offline documentation isn't important.

I'm saying offline documentation *bundled with a specific KiCad release*
isn't important.

If someone needs offline documentation, we should make it easy for them to
obtain the latest "snapshot" of any given doc branch from our website.
Just bundling a snapshot with the code release will mean that the docs are
not in sync with the code (because we don't have a team of doc writers who
keep the docs up-to-date at the same rate that we release code changes)

-Jon

On Wed, Jan 19, 2022 at 11:21 AM Gabriel Staples, ElectricRCAircraftGuy.com
 wrote:

> > I'm not sure that this is a very important feature in today's world.
>
> In many parts of the government, and in some research labs, offline
> documentation is still **very important** because they block nearly all of
> the internet. But, a healthy compromise would be to have online
> documentation only, but to have it downloadable as an html website package
> so you can still browse it when offline.
>
> Also, i can see some rural schools and areas not having good internet and
> being in trouble if someone like me wants to get the kids excited about
> KiCad but we can't load the documentation. So, again, it needs to be easily
> downloadable.
>
> In other words, please do make "online documentation" only, as it allows
> faster updates to it and better consistency, but please do also make the
> whole documentation site easily downloadable to be viewed in a browser when
> offline.
>
>
> Thanks!
>
> Gabriel Staples
>
> (sent from my Android)
>
> Le mar. 18 janv. 2022, 11:12 AM, Jon Evans  a écrit :
>
>> We have decided to update the online documentation in a rolling fashion,
>> meaning that new changes go "live" pretty quickly after being approved and
>> merged.
>>
>> The version that is bundled with the application is a snapshot in time
>> (at the point that software release was made).
>>
>> I think moving to an online-only help system is actually a good idea and
>> I've talked about this before some -- it would also make it easier to
>> improve the formatting of the documentation, since we would have only one
>> output format (HTML/CSS) to deal with.
>>
>> The main reason to include offline documentation (other than "because
>> that's how it's always been done with KiCad") is to provide documentation
>> that is accessible if the user's computer doesn't have an internet
>> connection.  I'm not sure that this is a very important feature in today's
>> world.
>>
>> -Jon
>>
>> On Tue, Jan 18, 2022 at 1:05 PM Tom A.  wrote:
>>
>>> I don't have view at all, not really a software engineer so may take a
>>> bit of spamming with some questions that may be quite obvious to others.
>>>
>>> My first question is why in the software Help section is so dated and
>>> online version much more up to date? It seems you can access online version
>>> from the software, so why to include old (probably no more relevant)
>>> documentation?
>>>
>>> Regards,
>>> Tomas
>>>
>>> On Tue, 18 Jan 2022, 17:17 Jon Evans,  wrote:
>>>
 I don't personally see the point of spamming the list with back and
 forth about setting up Git/Gitlab, installing dependencies, etc.

 But, I am not opposed to it if others don't care.

 -Jon

 On Tue, Jan 18, 2022 at 12:02 PM Marco Ciampa 
 wrote:

> On Tue, Jan 18, 2022 at 09:10:22AM -0500, Jon Evans wrote:
> > Hi Tomas,
> >
> > I've been loosely coordinating documentation updates for V6.  There
> are not
> > very many other people working on it.  We'd be happy to have your
> help.
> > If you contact me off-list I can help you get set up to make changes
> and we
> > can figure out where you'd like to start.
>
> I don't want to be rude but I do not understand. This list is almost
> silent. For sure some docs dev set-up instructions will not hurt
> anybody
> and perhaps there is something to learn (I bet I'll learn something
> anyway ...). So please do not discuss that elsewhere. This list was
> meant
> also for this.
>
> --
>
> Saluton,
> Marco Ciampa
>
> ___
> 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

>>> ___
>> Mailing list: https://launchpad.net/~kicad-developers
>> Post to : kicad-developers@lists.launchpad.net
>> Unsubscribe : https://launchpad.net/~kicad-developers
>> More help   : 

Re: [Kicad-developers] V6 documentation

[Gabriel Staples, ElectricRCAircraftGuy.com]

> I'm not sure that this is a very important feature in today's world.

In many parts of the government, and in some research labs, offline
documentation is still **very important** because they block nearly all of
the internet. But, a healthy compromise would be to have online
documentation only, but to have it downloadable as an html website package
so you can still browse it when offline.

Also, i can see some rural schools and areas not having good internet and
being in trouble if someone like me wants to get the kids excited about
KiCad but we can't load the documentation. So, again, it needs to be easily
downloadable.

In other words, please do make "online documentation" only, as it allows
faster updates to it and better consistency, but please do also make the
whole documentation site easily downloadable to be viewed in a browser when
offline.


Thanks!

Gabriel Staples

(sent from my Android)

Le mar. 18 janv. 2022, 11:12 AM, Jon Evans  a écrit :

> We have decided to update the online documentation in a rolling fashion,
> meaning that new changes go "live" pretty quickly after being approved and
> merged.
>
> The version that is bundled with the application is a snapshot in time (at
> the point that software release was made).
>
> I think moving to an online-only help system is actually a good idea and
> I've talked about this before some -- it would also make it easier to
> improve the formatting of the documentation, since we would have only one
> output format (HTML/CSS) to deal with.
>
> The main reason to include offline documentation (other than "because
> that's how it's always been done with KiCad") is to provide documentation
> that is accessible if the user's computer doesn't have an internet
> connection.  I'm not sure that this is a very important feature in today's
> world.
>
> -Jon
>
> On Tue, Jan 18, 2022 at 1:05 PM Tom A.  wrote:
>
>> I don't have view at all, not really a software engineer so may take a
>> bit of spamming with some questions that may be quite obvious to others.
>>
>> My first question is why in the software Help section is so dated and
>> online version much more up to date? It seems you can access online version
>> from the software, so why to include old (probably no more relevant)
>> documentation?
>>
>> Regards,
>> Tomas
>>
>> On Tue, 18 Jan 2022, 17:17 Jon Evans,  wrote:
>>
>>> I don't personally see the point of spamming the list with back and
>>> forth about setting up Git/Gitlab, installing dependencies, etc.
>>>
>>> But, I am not opposed to it if others don't care.
>>>
>>> -Jon
>>>
>>> On Tue, Jan 18, 2022 at 12:02 PM Marco Ciampa 
>>> wrote:
>>>
 On Tue, Jan 18, 2022 at 09:10:22AM -0500, Jon Evans wrote:
 > Hi Tomas,
 >
 > I've been loosely coordinating documentation updates for V6.  There
 are not
 > very many other people working on it.  We'd be happy to have your
 help.
 > If you contact me off-list I can help you get set up to make changes
 and we
 > can figure out where you'd like to start.

 I don't want to be rude but I do not understand. This list is almost
 silent. For sure some docs dev set-up instructions will not hurt anybody
 and perhaps there is something to learn (I bet I'll learn something
 anyway ...). So please do not discuss that elsewhere. This list was
 meant
 also for this.

 --

 Saluton,
 Marco Ciampa

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

Re: [Kicad-developers] V6 documentation

[Tom A.]

I agree that if the same documentation is taken as a snapshot of the latest
version at that time, it must be clearly noted for the user (and maybe
together with a note it is likely out of date compared to the online
version).

I will read the README files and we can go from there. Haven't really used
gitlab that much and I'm not quite a software engineer but will give it a
go.


Regards,
Tomas



On Wed, 19 Jan 2022 at 14:10, Jon Evans  wrote:

> The documentation lives in this git repo:
> https://gitlab.com/kicad/services/kicad-doc
>
> The same sources build the version on the website (docs.kicad.org) and
> the offline docs.
>
> If keeping the offline docs is important, I think the next best thing is
> to insert some extra text in the offline build that gives a warning that
> offline docs are likely to be outdated and links to the website.
>
> -Jon
>
> On Wed, Jan 19, 2022 at 8:28 AM Tom A.  wrote:
>
>> In my opinion it is great to have fall-back plan such as built in
>> documentation (which is particularly handy if you lost internet connection)
>> but at the moment it is too different from online version which is why I
>> raised this question.
>>
>> Assuming there is a reasonably easy way to export online docs into
>> something that can be bundled together with the software I see no harm in
>> continuing with both methods of reaching documentation. Obviously my
>> personal opinion.
>>
>> Where is the current online documentation stored, how to access/modify it
>> and how revisions are handled? Is there lifecycle process involved
>> (draft-under review-approved/released) or pretty much write it and ask
>> someone to look over it?
>>
>>
>> Regards,
>> Tomas
>>
>>
>> On Wed, 19 Jan 2022, 08:27 Marco Ciampa,  wrote:
>>
>>> On Wed, Jan 19, 2022 at 08:02:51AM +, Martijn Kuipers wrote:
>>> > If separate, you could update it more frequently. Just take care it is
>>> > understandable for which lkicad version it applies.
>>> >
>>> > Local docs is where I look first.
>>>
>>> Version matching should be handled by the packaging system in use, deb /
>>> rpm / etc. ... btw keeping docs as a separate package is a good idea and
>>> I think it is already so for most of the linux distributions...
>>>
>>> --
>>>
>>> Saluton,
>>> Marco Ciampa
>>>
>>> ___
>>> 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
>>
>
___
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

Re: [Kicad-developers] V6 documentation

[Jon Evans]

The documentation lives in this git repo:
https://gitlab.com/kicad/services/kicad-doc

The same sources build the version on the website (docs.kicad.org) and the
offline docs.

If keeping the offline docs is important, I think the next best thing is to
insert some extra text in the offline build that gives a warning that
offline docs are likely to be outdated and links to the website.

-Jon

On Wed, Jan 19, 2022 at 8:28 AM Tom A.  wrote:

> In my opinion it is great to have fall-back plan such as built in
> documentation (which is particularly handy if you lost internet connection)
> but at the moment it is too different from online version which is why I
> raised this question.
>
> Assuming there is a reasonably easy way to export online docs into
> something that can be bundled together with the software I see no harm in
> continuing with both methods of reaching documentation. Obviously my
> personal opinion.
>
> Where is the current online documentation stored, how to access/modify it
> and how revisions are handled? Is there lifecycle process involved
> (draft-under review-approved/released) or pretty much write it and ask
> someone to look over it?
>
>
> Regards,
> Tomas
>
>
> On Wed, 19 Jan 2022, 08:27 Marco Ciampa,  wrote:
>
>> On Wed, Jan 19, 2022 at 08:02:51AM +, Martijn Kuipers wrote:
>> > If separate, you could update it more frequently. Just take care it is
>> > understandable for which lkicad version it applies.
>> >
>> > Local docs is where I look first.
>>
>> Version matching should be handled by the packaging system in use, deb /
>> rpm / etc. ... btw keeping docs as a separate package is a good idea and
>> I think it is already so for most of the linux distributions...
>>
>> --
>>
>> Saluton,
>> Marco Ciampa
>>
>> ___
>> 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
>
___
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

Re: [Kicad-developers] V6 documentation

[Tom A.]

In my opinion it is great to have fall-back plan such as built in
documentation (which is particularly handy if you lost internet connection)
but at the moment it is too different from online version which is why I
raised this question.

Assuming there is a reasonably easy way to export online docs into
something that can be bundled together with the software I see no harm in
continuing with both methods of reaching documentation. Obviously my
personal opinion.

Where is the current online documentation stored, how to access/modify it
and how revisions are handled? Is there lifecycle process involved
(draft-under review-approved/released) or pretty much write it and ask
someone to look over it?


Regards,
Tomas


On Wed, 19 Jan 2022, 08:27 Marco Ciampa,  wrote:

> On Wed, Jan 19, 2022 at 08:02:51AM +, Martijn Kuipers wrote:
> > If separate, you could update it more frequently. Just take care it is
> > understandable for which lkicad version it applies.
> >
> > Local docs is where I look first.
>
> Version matching should be handled by the packaging system in use, deb /
> rpm / etc. ... btw keeping docs as a separate package is a good idea and
> I think it is already so for most of the linux distributions...
>
> --
>
> Saluton,
> Marco Ciampa
>
> ___
> 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

Re: [Kicad-developers] V6 documentation

[Marco Ciampa]

On Wed, Jan 19, 2022 at 08:02:51AM +, Martijn Kuipers wrote:
> If separate, you could update it more frequently. Just take care it is
> understandable for which lkicad version it applies.
> 
> Local docs is where I look first.

Version matching should be handled by the packaging system in use, deb /
rpm / etc. ... btw keeping docs as a separate package is a good idea and
I think it is already so for most of the linux distributions...

-- 

Saluton,
Marco Ciampa

___
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

Re: [Kicad-developers] V6 documentation

[Martijn Kuipers]

If separate, you could update it more frequently. Just take care it is
understandable for which lkicad version it applies.

Local docs is where I look first.

Just my 2cents.
Martijn

A quarta, 19/01/2022, 05:44, Ajith Narayanan  escreveu:

> Greetings!
>
> KiCad's documentation is in a standard source format (asciidoc) from which
> HTML/CSS are generated. Currently 'KiCad Help' just kicks off a browser
> pointing it to the local file(s) (e.g.
> /usr/share/doc/kicad/help/en/kicad.html). This is quite clean.
>
> In other words, KiCad already has a (version controllable) single source
> documentation that can generate both the locally installable documentation,
> as well output suitable to be published online on the web.  (Their styles
> could be different, say by applying different CSS -- many possibilities in
> the pipeline).
>
> A single source along with a capable rendering workflow with multiple
> targets (local documentation, web, epub, PDF via a LaTeX pipeline) etc are
> all enabled by this approach.
>
> I don't think there is anything to be gained by discontinuing local
> documentation. The disk usage is very small, tiny by today's standards, and
> the pipeline / workflow  is pretty much the same, it already exists.
>
> If at all somebody wants to be free of local documentation, then:  this
> need can be served by making kicad-doc-XXX a separately installable
> package, with optional dependency indicated. When not installed, KiCad Help
> would send the browser to the online documentation site (taking care to
> match the KiCad version to the URL to the correct documentation version). I
> feel, on that help page, we should advise the user to install the package
> locally if she would like to have local access.
>
> That's just my input.
>
> --Ajith
>
>
> On Wed, 19 Jan 2022 at 02:13, Jon Evans  wrote:
>
>> We have decided to update the online documentation in a rolling fashion,
>> meaning that new changes go "live" pretty quickly after being approved and
>> merged.
>>
>> The version that is bundled with the application is a snapshot in time
>> (at the point that software release was made).
>>
>> I think moving to an online-only help system is actually a good idea and
>> I've talked about this before some -- it would also make it easier to
>> improve the formatting of the documentation, since we would have only one
>> output format (HTML/CSS) to deal with.
>>
>> The main reason to include offline documentation (other than "because
>> that's how it's always been done with KiCad") is to provide documentation
>> that is accessible if the user's computer doesn't have an internet
>> connection.  I'm not sure that this is a very important feature in today's
>> world.
>>
>> -Jon
>>
>> On Tue, Jan 18, 2022 at 1:05 PM Tom A.  wrote:
>>
>>> I don't have view at all, not really a software engineer so may take a
>>> bit of spamming with some questions that may be quite obvious to others.
>>>
>>> My first question is why in the software Help section is so dated and
>>> online version much more up to date? It seems you can access online version
>>> from the software, so why to include old (probably no more relevant)
>>> documentation?
>>>
>>> Regards,
>>> Tomas
>>>
>>> On Tue, 18 Jan 2022, 17:17 Jon Evans,  wrote:
>>>
 I don't personally see the point of spamming the list with back and
 forth about setting up Git/Gitlab, installing dependencies, etc.

 But, I am not opposed to it if others don't care.

 -Jon

 On Tue, Jan 18, 2022 at 12:02 PM Marco Ciampa 
 wrote:

> On Tue, Jan 18, 2022 at 09:10:22AM -0500, Jon Evans wrote:
> > Hi Tomas,
> >
> > I've been loosely coordinating documentation updates for V6.  There
> are not
> > very many other people working on it.  We'd be happy to have your
> help.
> > If you contact me off-list I can help you get set up to make changes
> and we
> > can figure out where you'd like to start.
>
> I don't want to be rude but I do not understand. This list is almost
> silent. For sure some docs dev set-up instructions will not hurt
> anybody
> and perhaps there is something to learn (I bet I'll learn something
> anyway ...). So please do not discuss that elsewhere. This list was
> meant
> also for this.
>
> --
>
> Saluton,
> Marco Ciampa
>
> ___
> 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

>>> 

Re: [Kicad-developers] V6 documentation

[Ajith Narayanan]

Greetings!

KiCad's documentation is in a standard source format (asciidoc) from which
HTML/CSS are generated. Currently 'KiCad Help' just kicks off a browser
pointing it to the local file(s) (e.g.
/usr/share/doc/kicad/help/en/kicad.html). This is quite clean.

In other words, KiCad already has a (version controllable) single source
documentation that can generate both the locally installable documentation,
as well output suitable to be published online on the web.  (Their styles
could be different, say by applying different CSS -- many possibilities in
the pipeline).

A single source along with a capable rendering workflow with multiple
targets (local documentation, web, epub, PDF via a LaTeX pipeline) etc are
all enabled by this approach.

I don't think there is anything to be gained by discontinuing local
documentation. The disk usage is very small, tiny by today's standards, and
the pipeline / workflow  is pretty much the same, it already exists.

If at all somebody wants to be free of local documentation, then:  this
need can be served by making kicad-doc-XXX a separately installable
package, with optional dependency indicated. When not installed, KiCad Help
would send the browser to the online documentation site (taking care to
match the KiCad version to the URL to the correct documentation version). I
feel, on that help page, we should advise the user to install the package
locally if she would like to have local access.

That's just my input.

--Ajith


On Wed, 19 Jan 2022 at 02:13, Jon Evans  wrote:

> We have decided to update the online documentation in a rolling fashion,
> meaning that new changes go "live" pretty quickly after being approved and
> merged.
>
> The version that is bundled with the application is a snapshot in time (at
> the point that software release was made).
>
> I think moving to an online-only help system is actually a good idea and
> I've talked about this before some -- it would also make it easier to
> improve the formatting of the documentation, since we would have only one
> output format (HTML/CSS) to deal with.
>
> The main reason to include offline documentation (other than "because
> that's how it's always been done with KiCad") is to provide documentation
> that is accessible if the user's computer doesn't have an internet
> connection.  I'm not sure that this is a very important feature in today's
> world.
>
> -Jon
>
> On Tue, Jan 18, 2022 at 1:05 PM Tom A.  wrote:
>
>> I don't have view at all, not really a software engineer so may take a
>> bit of spamming with some questions that may be quite obvious to others.
>>
>> My first question is why in the software Help section is so dated and
>> online version much more up to date? It seems you can access online version
>> from the software, so why to include old (probably no more relevant)
>> documentation?
>>
>> Regards,
>> Tomas
>>
>> On Tue, 18 Jan 2022, 17:17 Jon Evans,  wrote:
>>
>>> I don't personally see the point of spamming the list with back and
>>> forth about setting up Git/Gitlab, installing dependencies, etc.
>>>
>>> But, I am not opposed to it if others don't care.
>>>
>>> -Jon
>>>
>>> On Tue, Jan 18, 2022 at 12:02 PM Marco Ciampa 
>>> wrote:
>>>
 On Tue, Jan 18, 2022 at 09:10:22AM -0500, Jon Evans wrote:
 > Hi Tomas,
 >
 > I've been loosely coordinating documentation updates for V6.  There
 are not
 > very many other people working on it.  We'd be happy to have your
 help.
 > If you contact me off-list I can help you get set up to make changes
 and we
 > can figure out where you'd like to start.

 I don't want to be rude but I do not understand. This list is almost
 silent. For sure some docs dev set-up instructions will not hurt anybody
 and perhaps there is something to learn (I bet I'll learn something
 anyway ...). So please do not discuss that elsewhere. This list was
 meant
 also for this.

 --

 Saluton,
 Marco Ciampa

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

Re: [Kicad-developers] V6 documentation

[Jon Evans]

We have decided to update the online documentation in a rolling fashion,
meaning that new changes go "live" pretty quickly after being approved and
merged.

The version that is bundled with the application is a snapshot in time (at
the point that software release was made).

I think moving to an online-only help system is actually a good idea and
I've talked about this before some -- it would also make it easier to
improve the formatting of the documentation, since we would have only one
output format (HTML/CSS) to deal with.

The main reason to include offline documentation (other than "because
that's how it's always been done with KiCad") is to provide documentation
that is accessible if the user's computer doesn't have an internet
connection.  I'm not sure that this is a very important feature in today's
world.

-Jon

On Tue, Jan 18, 2022 at 1:05 PM Tom A.  wrote:

> I don't have view at all, not really a software engineer so may take a bit
> of spamming with some questions that may be quite obvious to others.
>
> My first question is why in the software Help section is so dated and
> online version much more up to date? It seems you can access online version
> from the software, so why to include old (probably no more relevant)
> documentation?
>
> Regards,
> Tomas
>
> On Tue, 18 Jan 2022, 17:17 Jon Evans,  wrote:
>
>> I don't personally see the point of spamming the list with back and forth
>> about setting up Git/Gitlab, installing dependencies, etc.
>>
>> But, I am not opposed to it if others don't care.
>>
>> -Jon
>>
>> On Tue, Jan 18, 2022 at 12:02 PM Marco Ciampa  wrote:
>>
>>> On Tue, Jan 18, 2022 at 09:10:22AM -0500, Jon Evans wrote:
>>> > Hi Tomas,
>>> >
>>> > I've been loosely coordinating documentation updates for V6.  There
>>> are not
>>> > very many other people working on it.  We'd be happy to have your help.
>>> > If you contact me off-list I can help you get set up to make changes
>>> and we
>>> > can figure out where you'd like to start.
>>>
>>> I don't want to be rude but I do not understand. This list is almost
>>> silent. For sure some docs dev set-up instructions will not hurt anybody
>>> and perhaps there is something to learn (I bet I'll learn something
>>> anyway ...). So please do not discuss that elsewhere. This list was meant
>>> also for this.
>>>
>>> --
>>>
>>> Saluton,
>>> Marco Ciampa
>>>
>>> ___
>>> 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
>>
>
___
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

Re: [Kicad-developers] V6 documentation

[Tom A.]

I don't have view at all, not really a software engineer so may take a bit
of spamming with some questions that may be quite obvious to others.

My first question is why in the software Help section is so dated and
online version much more up to date? It seems you can access online version
from the software, so why to include old (probably no more relevant)
documentation?

Regards,
Tomas

On Tue, 18 Jan 2022, 17:17 Jon Evans,  wrote:

> I don't personally see the point of spamming the list with back and forth
> about setting up Git/Gitlab, installing dependencies, etc.
>
> But, I am not opposed to it if others don't care.
>
> -Jon
>
> On Tue, Jan 18, 2022 at 12:02 PM Marco Ciampa  wrote:
>
>> On Tue, Jan 18, 2022 at 09:10:22AM -0500, Jon Evans wrote:
>> > Hi Tomas,
>> >
>> > I've been loosely coordinating documentation updates for V6.  There are
>> not
>> > very many other people working on it.  We'd be happy to have your help.
>> > If you contact me off-list I can help you get set up to make changes
>> and we
>> > can figure out where you'd like to start.
>>
>> I don't want to be rude but I do not understand. This list is almost
>> silent. For sure some docs dev set-up instructions will not hurt anybody
>> and perhaps there is something to learn (I bet I'll learn something
>> anyway ...). So please do not discuss that elsewhere. This list was meant
>> also for this.
>>
>> --
>>
>> Saluton,
>> Marco Ciampa
>>
>> ___
>> 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
>
___
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

Re: [Kicad-developers] V6 documentation

[Jon Evans]

I don't personally see the point of spamming the list with back and forth
about setting up Git/Gitlab, installing dependencies, etc.

But, I am not opposed to it if others don't care.

-Jon

On Tue, Jan 18, 2022 at 12:02 PM Marco Ciampa  wrote:

> On Tue, Jan 18, 2022 at 09:10:22AM -0500, Jon Evans wrote:
> > Hi Tomas,
> >
> > I've been loosely coordinating documentation updates for V6.  There are
> not
> > very many other people working on it.  We'd be happy to have your help.
> > If you contact me off-list I can help you get set up to make changes and
> we
> > can figure out where you'd like to start.
>
> I don't want to be rude but I do not understand. This list is almost
> silent. For sure some docs dev set-up instructions will not hurt anybody
> and perhaps there is something to learn (I bet I'll learn something
> anyway ...). So please do not discuss that elsewhere. This list was meant
> also for this.
>
> --
>
> Saluton,
> Marco Ciampa
>
> ___
> 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

Re: [Kicad-developers] V6 documentation

[Marco Ciampa]

On Tue, Jan 18, 2022 at 09:10:22AM -0500, Jon Evans wrote:
> Hi Tomas,
> 
> I've been loosely coordinating documentation updates for V6.  There are not
> very many other people working on it.  We'd be happy to have your help.
> If you contact me off-list I can help you get set up to make changes and we
> can figure out where you'd like to start.

I don't want to be rude but I do not understand. This list is almost
silent. For sure some docs dev set-up instructions will not hurt anybody
and perhaps there is something to learn (I bet I'll learn something
anyway ...). So please do not discuss that elsewhere. This list was meant
also for this.

--

Saluton,
Marco Ciampa

___
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

Re: [Kicad-developers] V6 documentation

[Jon Evans]

Hi Tomas,

I've been loosely coordinating documentation updates for V6.  There are not
very many other people working on it.  We'd be happy to have your help.
If you contact me off-list I can help you get set up to make changes and we
can figure out where you'd like to start.

Best,
Jon

On Tue, Jan 18, 2022 at 9:03 AM Tom A.  wrote:

> Hi all,
>
> I've been using KiCad daily for last couple of years and I think it's
> great project with a lot of potential.
>
> Congratulations on V6 release to everyone involved.
>
> I had few challenges with new version and found documentation being rather
> weak. Is there someone working on it (dedicated) or its just random effort?
> Since I use a lot of functions and trained few people to use the software,
> I could volunteer to work on it. I've written lots of documentation for OEM
> manufacturer and believe am more than capable of it.
>
> I could also translate package to my native language (LT).
>
> Need directions please :)
>
> Regards,
> Tomas
> ___
> 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

[Kicad-developers] V6 documentation

[Tom A.]

Hi all,

I've been using KiCad daily for last couple of years and I think it's great
project with a lot of potential.

Congratulations on V6 release to everyone involved.

I had few challenges with new version and found documentation being rather
weak. Is there someone working on it (dedicated) or its just random effort?
Since I use a lot of functions and trained few people to use the software,
I could volunteer to work on it. I've written lots of documentation for OEM
manufacturer and believe am more than capable of it.

I could also translate package to my native language (LT).

Need directions please :)

Regards,
Tomas
___
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