[Battlemesh] Fwd: Google Season of Docs projects for OpenWrt
fboehm at aon.at
fboehm at aon.at
Wed Jun 10 06:13:01 CEST 2020
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
More information about the Battlemesh