On 13/11/2017 13:11, Jo-Philipp Wich wrote:
Hi,
The wiki is working for me. it's great to have the ToH. Also the
device pages are great. However the wiki is not always completely
correct and may be just wrong. It's a wiki, change it! A wiki is
always changing.
I believe that a wiki is no alternative for a proper, curated
documentation. I've also seen many instances where user contributed
information was either incomplete or even factually wrong.
Yeah, but proper documentation (not tutorials, I mean available commands
and their meaning)
can only be written by developers. So far on the wiki I've seen (even
large) contributions of mostly user-oriented tutorials.
Someone did add/change the documentation part, (especially after I asked
for it in the github PRs)
but I have no idea of how correct that is, or how to test it myself on
my hardware.
This is why I think having developer-grade and core documentation (like
all uci config files for default system) in git is better, so you can
enforce contributors to update it with their changes
and check that they aren't writing garbage in it.
While tutorials, ToH, package table/lists and other user-oriented parts
stay in the wiki.
I don't think forcing the whole wiki into the readthedocs site is a good
idea just as
leaving all documentation in the wiki is not great.
Another thing I noticed is that some documentation actually seem to have
devolved compared to the OpenWrt wiki. I wrote large parts of
https://wiki.openwrt.org/doc/uci/network - now compare that with
https://lede-project.org/docs/user-guide/network_configuration.
Not even did I struggle to find that page in the first place within the
LEDE wiki, I also couldn't find any trace of the missing ip rule or
route action documentation.
Also TOH != documentation.
~ Jo
I split that page into separate articles under Network Configuration [1]
to improve its readability.
Same was done for other articles like the dnsmasq one that was split in
DHCP and DNS articles.
Information in LEDE wiki is arranged by topic, not by what config file
it is in.
I think the OpenWRT wiki arrangement for that documentation is not
intuitive for everyone but developers, imho.
(I also converted instructions to use uci commands instead than manual
text editing with vi, as again
vi isn't terribly user-friendly and mistakes in manual edits can screw
up the configuration file)
It seems the mentioned part is missing, it's probably a mistake on my
part, I'm sorry for that.
I'll have a look this evening to fix it.
1. https://lede-project.org/docs/user-guide/start#basic_configuration
-Alberto
_______________________________________________
Lede-dev mailing list
Lede-dev@lists.infradead.org
http://lists.infradead.org/mailman/listinfo/lede-dev
