[OpenWrt-Devel] Documentation in the tree? [Was: Re: [PATCH v3] gemini: Support sysupgrade on DIR-685]

[Alberto Bursi]

On 21/05/19 11:13, Petr Štetiar wrote:
> Linus Walleij <linus.walleij at linaro.org> [2019-05-20 23:48:41]:
>
> [adding Alberto, Thomas and Javier to the Cc: loop]
>
>> how you want the sysupgrade to work.
> it's just preferred to share as much common code as possible.
>
>> Maybe we could open a documentation page for new devices, like here is how
>> we want you to implement sysupgrade, I had a hard time to figure out that
>> all was circuling around the platform.sh script and how that was called from
>> the core sysupgrade.
> indeed, some documentation would be certainly nice and welcome, but I think,
> that it's clear, that having the documentation decoupled from the code (wiki
> today) leads often to outdated (incomplete, even factually wrong or misleadin)
> documentation which might be even more confusing for the starters then current
> "read the code Luke" approach.
>
> I mean, maybe this is the right time to rethink[1,2], so we could have
> docs/Documentation folder in the source tree, like it's done in the kernel and
> other projects.
>
> 1. https://lede.readthedocs.io/en/latest/
> 2. https://lists.openwrt.org/pipermail/openwrt-devel/2017-November/009888.html
>
> -- ynezz


The only clear thing is that documentation does not write itself and that

you can't rely on users to write developer documentation.

Where it is kept is irrelevant, what is relevant is that people doing 
commits

(members and contributors) actually write it and keep it updated 
wherever it is kept.


I'd like to point out that it was yours truly that deleted the 
documentation

folder in the current OpenWrt tree

with commit 882f4d2d63272abce8c1966983aa10178e2e971f

as it was horribly outdated and completely useless

(and we got people rightfully complaining about it in the forums).


-Alberto.

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.infradead.org/pipermail/openwrt-devel/attachments/20190521/b785c7dd/attachment.htm>
-------------- next part --------------
_______________________________________________
openwrt-devel mailing list
openwrt-devel at lists.openwrt.org
https://lists.openwrt.org/mailman/listinfo/openwrt-devel