[LEDE-DEV] Lede/Openwrt documentation

[John Norton]

On 27/10/2017 13:58, Javier Domingo Cansino wrote:
>> 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,
>

I see this can be a good way forward, but I have some questions.

I still think user-level documentation must have a decent wiki-like 
editor in the browser, because github's editor
sucks big way, and isn't suited for proper formatting and similar. I'm 
not that happy with docuwiki's editor (current editor) either.
Does your proposed system have something like that?

The wiki currently hosts and renders tables on the basis of data 
acquired and stored in a database.
The table of packages and table of hardware. They are searchable and can 
be filtered.
The table of hardware has a template system to let people add new 
devices to the "hardware database".
https://lede-project.org/meta/create_new_dataentry_page
Is there a way to do something like that with this new system?

Docuwiki allows people to translate the same pages to other languages, 
and keeps track of what pages have an out-of-sync translation.
There are at least a couple asian translators 
(chinese/japanese/korean/whatever) and a russian guy that did some work 
there.

I mean I'm not a fan of the docuwiki, it's a brick and lacks 
flexibility, but it is still better than plaintext.

-Alberto