[LEDE-DEV] Lede/Openwrt documentation

[Alberto Bursi]

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