← Back to team overview

kicad-developers team mailing list archive

Re: V6 documentation

 

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
<ercaguy@xxxxxxxxx> 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 <jon@xxxxxxxxxxxxx> 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. <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
>>
>

Follow ups

References