[LEDE-DEV] Lede/Openwrt documentation

[Javier Domingo Cansino]

>         But it seems like a) way more hassle than editing a wiki directly and b) requires a github account.

The github account is the same as the wiki account, but I do agree
that is more hassle mainly because it's not an integrated experience

>         I do some stuff with github, but so far directly editing the wiki was less anoying than using the github editors (I use both the github editor and github wiki for other purposes and do not really like them too much)

My focus here is not to deter too much eventual contributions, but
boost the amount/quality/easiness of complex contributions that can be
made

>         So I tried that, it appears to be in a middle ground, not as convoluted as I expected it, but also not as "direct" as editing the current wiki. As you promised most of the additional steps are reduced to reading a bit and clicking through. I guess I might even try to add details under such a scheme, but the hurdles would be higher (which might not be a bad thing in itself).

I don't mind developing a guide if you would find it easier that way [1]

>         Wasted time mostly in assessing whether I really want to do this multiple times, while editing the wiki feels more immediate (I am ignoring the fact that the github editor is pretty plain and does not offer any help in how to format things nicely/correctly; I assume one gets used to that and the current wiki editor is not that great either)

I know the feeling, I wish there was an easier way, which probably
with time will be possible to hook, but for now I would just focus on
the port and the content.


>         Well, I am around for some time, but my 10 year younger self, upon seeing the raw .rst .n the github editor, would have just bailed out...

Agreed

>         I am not 100% convinced that the LEDE user guides lend themselves to such a continuous text representation.

They don't! I had to edit most of the Quick Start guide to have a
single flow. I think however now is more clear on the possibilities
offered.

>         Ideally the user would not need to deal with the under laying syntax (unless they would want to) a WYSIWYG-Interface for casual edits makes things friendlier to newcomers IMHO.

Yep, if you check out [1] people actually recommends using an online
visualizer. http://rst.ninjs.org

I do agree that it would really cool to have an integrated experience
though, although my main focus with this proposal is:

 * Restructure content as a book, so that it can be exported as
singlehtml, pdf, ebook
 * Gather user feedback on what parts are not clear/need to be fixed
through the issue tracking
 * Ease translations through already available online translation platforms

On later stages:

 * Transform the documentation in a fully fledged book that can serve
as a manual for openwrt
 * Version different API versions depending on the release
 * Track changes between versions from the user perspective
 * Document infrastructure stuff like adding buildbot nodes etc.
 * Document internal software and libraries (unless we generate a new
project for each of them to be portable/usable in other
distributions/OS)

>         Given the fun to edit the .rst without any help this kind of checking seems advisable ;)

Agreed, I will add it to the stuff to be done after the decision. My
idea for now was:
 * Add checks in internal links
 * Add checks to external links
 * Make sure that the documentation compiles

>         Just coming from one of the user guides, so admittedly biased and remote from the core documentation; a book would only superficially "bind" the sqm guide (https://lede-project.org/docs/user-guide/sqm) and the qos guide (https://lede-project.org/docs/user-guide/traffic_shaping) into something coherent, they still would not be of one style and scope. But both certainly are better than not having either of them.

We would need to edit the content for organizing it as a book. We can
easily add a chapter of use cases that can be implemented using
OpenWRT/LEDE, and those guides be part of it.

I don't hide that it will involve work, but I am confident that the
result will be a more manageable guide to master the project
possibilities.

Javier

[1] a base guide: https://socorro.readthedocs.io/en/v8/writingdocs.html