[Battlemesh] Fwd: Google Season of Docs projects for OpenWrt

[fboehm at aon.at]

On 09.06.20, Baptiste Jonglez wrote:
> Project 1 is focused on the documentation tooling because we thought it
> would be too hard for a non-openwrt-developer to also write low-level
> documentation.  But if you think you can do both, that's great!

The audience for Project 1 and 2 seems to be developers.
The audience for Project 3 to 5 seems to be regular or heavy users.
I'm mostly interested in Project 1 which has the following proposed tasks:

1. choose a documentation system (mkdocs, sphinx…) that will be applied 
consistently to all components
2. transfer all documentation related to each component directly into 
the code repository of the component
3. setup a system that builds all components documentation and makes the 
result easily available in a single place
4. reorganize / improve each component documentation to improve 
consistency and readability

Within Project 1 I'm mostly interested in Task 4. As an author I'm 
afraid I wouldn't want to work on task 1 to 3.

> Regarding the format, I don't know what you mean by "proofread book" but
> https://openwrt.org/google-season-of-docs  makes it clear that we want to
> move away from the wiki and use a uniform documentation system for all
> OpenWrt core components (probably mkdocs).

Here's a description of what I mean with "proofread book":

I would write all chapters myself but I would need one or more OpenWRT 
experts to discuss the table of contents and to proofread the chapters. 
This implies that I wouldn't want to use a collaboration tool where 5 or 
10 people can simultaneously add/remove/change content (like in a Wiki). 
I assume Google expects some sort of collaboration. So my 
"single-author" requirement might be a disqualifier.

The deliverable could be as simple as a looong TXT file (or some kind of 
Markdown format) plus some pictures / graphics / code-snippets to 
improve the reading experience. In any case a basic file format that can 
be postprocessed and published in any other format (HTML, PDF, ...). I'm 
afraid the content couldn't be easily split up and embedded into the 
different code repositories because it's meant to be a coherent text.

I guess it's best to think of my proposal as a book with the title 
"Beginners guide for OpenWRT developers". My job is done when Edition 1 
of this book is finished. Unfortunately I can't solve the problem that 
later on nobody would want to add or revise chapters and publish further 
Editions.

Franz