[LEDE-DEV] Lede/Openwrt documentation

[Javier Domingo Cansino]

> 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.

If someone has an small change to do, it's not about formatting, but
rather typos etc. The process can be done seamlessly through the
Github interface:
 * In the page you are at, click on edit on github
 * Click on edit the file, and it will ask you to fork it in your
github account.
 * Once you have finished editing, you click on save changes
 * You then are asked to submit your changes

Of course on the background, github is creating a fork, making a
commit to a branch created for this change and opening a pull request,
but it's quite seamless to the user

> first of, I am just a very casual contributor; only added a few details to the sqm user guide, so I do not assume my word having much weight

Part of this design with github is not to make it harder for casual
contributors, so feedback is welcome.

> Well, just from my perspective, if I had to create PRs for my changes and additions to the sqm user guide, I certainly would not have made one; I would have collected the new information at a completely different site and just posted links to the forum (or asked Rich Brown to add a link to the "official" lede sqm guide).

Sebastian, would you mind trying to do a change in
https://lede.readthedocs.org/ ? I really want to see if you feel it as
cumbersome as it seems I have described it.

> As a casual contributor I do value my time way over any strong "corporate identity" or structure enforcements.

If you could please try to make a change in the link above, and give
me feedback on where you wasted time it would be awesome. As I said, I
don't mind developing a how to make a change guide, but I believe
Github has done it quite easy for non experienced users.

Also, the idea of structure enforcement is not something compulsory
but something the new system could help have. If you want to add
random chapters anywhere in the docs without having an order, it's
still possible.

Just in case, I am trying to have something like what Buildroot has as
documentation: https://buildroot.org/downloads/manual/manual.html. RTD
is just one way to obtain this.


> 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.

Well, there are two ways to link things in sphinx. First, you have
same page references, part of RST syntax, that just use `Title`_ to
link to the titles in the same page. Second, you have 2 ways to
reference other pages, the one I prefer is by setting the
document:title you want to link, and the second one is by having tags
above titles that you reference from anywhere in the documentation
http://www.sphinx-doc.org/en/stable/markup/inline.html#ref-role

With the setup of Github, I can easily CI for the docs that checks for
missing references/broken links to avoid content corruption. This is
something built-in within sphinx (make check), and can be checked on
each of the changesets submitted, so that integrity of the
documentation is maintained. I can configure the toolset for this.

> 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.

I am just going for one of the documentation tools I know in use. Some
other competitors are:

 * Sphinx http://www.sphinx-doc.org/en/stable/index.html
 * GitBook https://www.gitbook.com/
 * DocGen http://mtmacdonald.github.io/docgen/docs/index.html

I don't mind using other syntaxes, as my focus is to change the
documentation from a Wiki into a Book structure.

Cheers,

Javier