kicad-developers team mailing list archive

[Ajith Narayanan <ajith@xxxxxxxxxxxx>]

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 <jon@xxxxxxxxxxxxx> 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. <ta8936@xxxxxxxxx> 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, <jon@xxxxxxxxxxxxx> 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 <ciampix@xxxxxxxxxx>
>>> 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@xxxxxxxxxxxxxxxxxxx
>>>> Unsubscribe : https://launchpad.net/~kicad-developers
>>>> More help   : https://help.launchpad.net/ListHelp
>>>>
>>> _______________________________________________
>>> Mailing list: https://launchpad.net/~kicad-developers
>>> Post to     : kicad-developers@xxxxxxxxxxxxxxxxxxx
>>> Unsubscribe : https://launchpad.net/~kicad-developers
>>> More help   : https://help.launchpad.net/ListHelp
>>>
>> _______________________________________________
> Mailing list: https://launchpad.net/~kicad-developers
> Post to     : kicad-developers@xxxxxxxxxxxxxxxxxxx
> Unsubscribe : https://launchpad.net/~kicad-developers
> More help   : https://help.launchpad.net/ListHelp
>