[OpenWrt-Devel] Documentation in the tree? [Was: Re: [PATCH v3] gemini: Support sysupgrade on DIR-685]
bobafetthotmail at gmail.com
Tue May 21 03:35:39 PDT 2019
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
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
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
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
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.
More information about the openwrt-devel