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