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

[Baptiste Jonglez]

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:

  https://files.polyno.me/openwrt/doc/index.html
  git clone git://git.polyno.me/openwrt-doc

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:

- 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;

- 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;

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

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

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

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?

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

Thanks,
Baptiste

PS: for the record, here is a set of questions that (I hope) would be
answered by this new documentation:

- how can I build an image for my device?
- how do I add UCI/netifd support for a new tunneling protocol?
- how do I enable a kernel option for my target/subtarget?
- how can I package my favourite software for LEDE?
- what is the difference between target, subtarget and profile?
- how do I work with kernel patches?
- how do I listen to particular ubus events from a shell script?
- how do I parse UCI config from C? shell? lua?
- how do all these ubox/netifd/ubus/procd things work together anyway?
- what is the format of /etc/board.json?
- how do I add a new target?
- how do I write a procd init script?
- (probably tons more...)

This kind of questions can currently be answered somewhat by reading the
devel doc on the wiki [1,2,3], but information is scattered around,
incomplete, and very often outdated (though it has improved with LEDE).
Quite often, technical questions are asked (and answered!) directly on the
mailing list, which makes it even harder to find in the future.

For reference, some questions that I think this documentation effort
SHOULD NOT address, at least not initially:

- does OpenWrt run on device X?
- how do I add a port redirection in the firewall?
- how do I configure package X from the external feed?

The wiki is currently fine for this, and such broad documentation
requires a tremendous amount of work.  Let's stay reasonable and not
reinvent all wheels at the same time :)



[1] https://wiki.openwrt.org/doc/guide-developer and https://lede-project.org/docs/guide-developer/start
[2] https://wiki.openwrt.org/doc/devel/packages
[3] https://wiki.openwrt.org/doc/devel/patches and https://lede-project.org/docs/guide-developer/use-patches-with-buildsystem
[4] https://docs.djangoproject.com/en/1.11/
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 833 bytes
Desc: not available
URL: <http://lists.infradead.org/pipermail/lede-dev/attachments/20171025/a96c35ad/attachment.sig>