[LEDE-DEV] [OpenWrt-Devel] [RFC] A new developper documentation for OpenWrt/LEDE
jo at mein.io
Thu Oct 26 14:34:55 PDT 2017
first of all I think that is a great initiative!
> So, here is a RFC proposal of a new developer documentation based on
> git and Sphinx:
> https://files.polyno.me/openwrt/doc/index.html git clone
The layout is okay and the ASCII markup looks reasonably simple to allow
for distraction-free text writing so LGTM here.
> This is really early work in progress, because it's good to have
> early feedback before I spend too much time on this :)
> The idea (which of course needs to be discussed) would be to keep
> this documentation in the same git repository as the main project.
> The main advantages compared with the wiki ("developer guide"  and
> associated pages [2,3]) would be:
That would be fine with me. There used to be some rudimentary
documentation in the past (see
but it never got really updated.
> - ensuring the doc is reasonably up-to-date, because of fate
> sharing: whenever a patch modifies something substantial in the code
> base, it can update the documentation at the same time;
Such a policy can be introduced once the docs are reasonably complete,
before that it would likely put off contributors.
> - more focused scope: the scope is explicitly limited to developer
> documentation. This makes it easier to produce good, complete and
> consistent documentation. Also, as a contributor, searching for a
> particular topic would become easier than in the wiki;
I like that, yes.
> - allow release branches for the documentation. For instance, if a
> feature is changed in trunk, the documentation in the 17.01 branch
> would still be correct for LEDE 17.01. Likewise, when backporting a
> feature from trunk to a stable release, the associated documentation
> would be backported as well. This is exactly what Django does with
> its documentation .
That would be an upside as well; while I do not expect release branch
documentation to receive much maintenance it would at the very least
ensure that future documentation updates do not invalidate config that
used to be correct for a past release.
> On the downside, it would become harder to contribute to the
> documentation: this is likely a reason for the failure of the LEDE
> "web presence". But I think another important reason for this
> failure was the scope, which was too broad (both user + developer
That is a valid point but I would give it a try; after all I suspect
this documentation to target contributors already aware of how to use Git.
> Of course, this proposal is not meant to *replace* the existing
> documentation on the wiki, but rather to *complement* it. In my
> opinion, this new doc would serve as a detailed and up-to-date
> reference for OpenWrt internals, while the wiki would still be
> extremely useful for user-oriented documentation (which hopefully
> would become even more relevant and accurate thanks to this new
> reference documentation).
I think we can figure out a way to automatically mirror the
documentation to the wiki so that users have a common location for user
and developer documentation.
> I can commit to setting it up, and help keeping it alive over the
> next few months/years. But of course it is not possible nor
> desirable to do this alone! Help would be required in the following
> 1) define the general structure of the doc: what should go in, what
> shouldn't, and how to organize the content; 2) initial effort:
> importing/refreshing relevant bits from the wiki, and writing the
> rest; 3) define some consensual rules on how to keep the doc
> up-to-date with the codebase.
You can count me in on 1) and 2). 3) should be deferred until a
reasonable base line is established. To simplify bootstrapping the
project we can also setup a scratch repo somewhere with direct push
access to documentation contributors.
> Now for the questions:
> - does this seem to go in the right direction?
> - would all developers be willing to spend a reasonable amount of
> time and effort to keep this documentation project alive and
> up-to-date over time?
I cannot speak for the others but I am personally interested in working
on the documentation. I also wrote parts of the existing uci references
and generally like working on such things. I cannot promise that I'll
have much time to write lots of text but I can certainly explain things
and help with answering questions.
> - what should be the general structure of this documentation? It
> would have been nice to brainstorm on this at the OpenWrt summit,
> but unfortunately I cannot attend.
It might make sense to set up an etherpad here to gather some structural
More information about the Lede-dev