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/
signature.asc
Description: PGP signature
_______________________________________________ openwrt-devel mailing list openwrt-devel@lists.openwrt.org https://lists.openwrt.org/cgi-bin/mailman/listinfo/openwrt-devel
