[LEDE-DEV] Lede/Openwrt documentation

[Javier Domingo Cansino]

> This problem is well-known [1,2] and can be solved by having access to a
> common ancestor between the two versions.  A possible way to do this would
> be to convert each wiki to a git repository [3], merge the two histories
> using git, and then convert back the git repository to a dokuwiki
> structure.  It sounds tedious but feasible.

As it looks like there are no clear decisions, I would like to propose
the following changes.

Git backed documentation:
 * It's easier to have all the content at a glance sorted in folders
to help structure the documentation
 * You can move content between pages easier

Use github as a place to host the document repository:
 * There are buildhooks from services integrated, such as github pages
or readthedocs that make it transparent to collaborate
 * Users can provide feedback through issues on missing docs, giving
tips to contributors to see what areas can be improved
 * Discussions about documental structure happen openly, easing burden
on people maintaining documentation by having an specific pipe
everything goes through
 * Contributions can be reviewed or automatically contributed if diff
< 100 lines (I can do a simple bot for that)

Integrate existing openwrt docs inside lede structure.
 * Having an structured documentation helps user know where to look
for the content
 * Makes easier to spot a place to write your contribution at
 * It is more user / dev-newbie friendly

Switch to sphinx
 * Most of the times there is no clue on where to place the
documentation, so you create a new wiki page, this leads to duplicate
information
 * Can generate HTML Single page, pdf, epub, etc. Although the usual
one is the multipage HTML
 * Can be hosted in readthedocs and integrated with github so that
every deployment is automatic
 * Can tag versions, so in the event we finally reach a good
documentation, users can browse different docs for each version
 * It's industry standard for project documentation. Not only about
documenting python
 * It has good to go skins that are proven to be easy to read
 * More complete syntax (if something like that would be required

Drawbacks I see:
 * Contributions in the wiki are instant, here they would have a
proper process to review.
 * There is a migration effort to be done, greater than just merging
docs in the same place

I volunteer however to setup today an example with the current lede
docs in sphinx, so that you can see the look and feel I am speaking
about.

Also, openwrt.readthedocs.org is taken but if we were to make official
this proposal, I would contact the current owner or rtd people to get
it transferred.

Cheers,

-- 
Javier Domingo Cansino