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

[Jo-Philipp Wich]

Hi Baptiste,

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
> git://git.polyno.me/openwrt-doc

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" [1] and
> associated pages [2,3]) would be:

That would be fine with me. There used to be some rudimentary
documentation in the past (see
http://git.lede-project.org/882f4d2d63272abce8c1966983aa10178e2e971f)
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 [4].

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
> documentation).

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
> areas:
> 
> 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?

Definitely!

> - 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
ideas.


Cheers,
Jo