[LEDE-DEV] [RFC] A new developper documentation for OpenWrt/LEDE

[Eric Luehrsen]

On 10/25/2017 12:19 PM, John Norton wrote:
>
>
> On 25/10/2017 17:22, Baptiste Jonglez wrote:
>> Hi,
>>
>> As an occasional contributor to OpenWrt/LEDE, I am often frustrated 
>> by the
>> lack of good technical documentation.  By "technical documentation", I
>> mean a detailed, reasonably complete and up-to-date documentation on 
>> "How
>> things work under the hood" and "How to do advanced stuff with the build
>> system".  That is, documentation targeted at hackers, contributors, and
>> would-be developers.
>>
>> So, here is a RFC proposal of a new developer documentation based on git
>> and Sphinx:
>>
>
> I share the frustration, and imho the lack of good docs is a big 
> barrier to serious contributions
> (I mean beyond adding support for new devices).
>
> I like your idea, I don't think that being in git would be bad for 
> developer docs, as:
>
> people actually writing these things should be developers in the first 
> place so it's reasonable
> to assume that they won't be turned off by having to use git, as they 
> use git anyway.
>
> Also the fact that to change the docs you need to get past a person 
> with commit access
> should help filter and correct changes by someone that actually knows 
> well the system.
>
> We can easily import the text from git to be shown (read-only) in the 
> wiki too,
> for the sake of easy access for all.
>
> What MUST live in the wiki is user-oriented documentation,
> as it is the one most non-developers contribute to.
>
> -Alberto

User-oriented documentation should go with specific packages in their 
respective git home. I have seen where packages like adblock, 
travelmate, and odhcpd (partially) have their documentation in 
.../files/README.md. I have made sure the same is done for Unbound. The 
focus of these should be "this package only," and optionally if not too 
wordy or complex, some minor recipes for integrating the package with 
another. External packages and core packages (like dnsmasq) should 
really all follow this pattern. Also, make sure the LuCI page(s) have a 
formatted link to the repo (github or...).

-Eric