On 21/05/19 12:11, Petr Štetiar wrote:
Alberto Bursi <bobafetthotm...@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@lists.openwrt.org
https://lists.openwrt.org/mailman/listinfo/openwrt-devel
