[LEDE-DEV] Lede/Openwrt documentation

[Alberto Bursi]

On 11/11/2017 01:40 AM, Javier Domingo Cansino wrote:
> Hello,
>
> I have continued working on the docs https://lede.rtfd.io. It now
> contains a Proof of Concept, with the following features:
>
> * Documentation can be exported in different formats, html (hosted in
> https://lede.rtfd.io), single page html, pdf, ebook etc.
> * Documentation has been edited in a single sorted flow, with
> references between resources, making it easy to navigate, this works
> in pdf, single html, etc, versions too
> * It sets the base to have a complete documentation and avoid
> duplicates, checking links (sphinx has a linkchecker), and references
> within the document
>
> Technical things that still need to be done before replacing the main
> wiki with this:
>
> * Port the rest of the content (only the quickstart guide has been
> ported). This is a heavy task because of the structural difference
> between a wiki and a book.
> * Insert Table of Hardware with filter features etc.
> * Create a guide on how to contribute to the book
>
> As you can see, I didn't implement some those essential features
> because first I would like to see:
>
> * If you like what you see
> * if you have any needs apart from what I did and stated is needed
> * A decision to proceed with a roadmap and help if possible
>
> I don't have clear what process needs to be followed for the
> decision/roadmap, so I leave that up to you, and will reply with
> ideas.
>
> Cheers,
>
> Javier
>
>

Well, I like readthedocs, but I still think it is too simplistic for our 
needs. The issues I raised are still there.

Editing the page happens through Github's web editor and web interface, 
both are utter garbage for code, and even more so for text-based 
documentation. Plus the whole fact that you are required to open a PR, 
which is a completely alien concept for non-developers.

Second thing is that internal links to other pages should adjust 
themselves automatically. This is really a big thing, as I'm not a fan 
of going and fixing dozens of links manually every time I or some newbie 
moves/changes something.

So basically still some kind of wiki system for the frontend, but with 
git-based versioning.

Have you looked at git-based wikis? because there is no way around it, 
we still need a wiki-like system (yes, even Github's own wiki is better 
than its web code editor)
https://www.perforce.com/blog/comparison-of-git-powered-wikis-in-cloud-based-scm-tools
I don't know if the internal link thing is handled by all the wikis in 
the following list, but they at least all allow wiki-like internal links.

-Alberto