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

[Alberto Bursi]

On 21/05/19 12:11, Petr Štetiar wrote:
> Alberto Bursi <bobafetthotmail at gmail.com> [2019-05-21 11:37:31]:
>
>> The only clear thing is that documentation does not write itself and that
>> you can't rely on users to write developer documentation.
> You actually can enforce it somehow, as you either include/update
> documentation to reflect your changes or your contribution won't be considered
> for merge/review.
>
> It's not a panacea, but it works relatively well in the kernel (DT docs for
> example).
>

And this can't be done with the docs in a wiki because?

That's just an implementation detail.

What matters is that someone is enforcing the rule to write and update docs.

This is what isn't happening.


>> with commit 882f4d2d63272abce8c1966983aa10178e2e971f
>> as it was horribly outdated and completely useless
> Maybe, that at that time GitHub considered Tex binary format and thus wouldn't
> allow web based PRs, thus limiting potential contributions? :-)

Yeah, because a lot of people contributed to the LEDE site when it was 
source in Github.

Github web interface is trash, and it's not user-friendly even for code 
contributions.

It's completely alien for people that want to contribute docs.



> I think, that you either have approachable documentation format(Markdown/ReST)
> and tooling around, which would allow easy contributions or you end up with
> the outdated documentation.
>
> -- ynezz


The wiki is working fine for user documentation, we have people that 
reworked a lot of the docs,

like for example the firewall section was completely rewritten to update 
it,

and there is random people that add stuff every now and then.

There are a couple semi-official maintainers for VPN and other hot topics.

(and I know, I'm notified of EVERY edit ANYONE does in the wiki)


The only thing that is lacking is the developer docs, which as I said 
cannot

be written by users, no amount of additional user-friendliness will help.

It has to be written by project members or contributors that actually 
worked on the code.


Since this is a project-wide thing you need to decide it among 
yourselves, and then start writing it

or enforce the rules on contributors.


-Alberto


_______________________________________________
openwrt-devel mailing list
openwrt-devel at lists.openwrt.org
https://lists.openwrt.org/mailman/listinfo/openwrt-devel