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
_______________________________________________
Lede-dev mailing list
Lede-dev@lists.infradead.org
http://lists.infradead.org/mailman/listinfo/lede-dev
