[LEDE-DEV] Lede/Openwrt documentation

Sun Nov 12 14:21:03 PST 2017

Hi Javiet,

> On Nov 12, 2017, at 22:24, Javier Domingo Cansino <javierdo1 at gmail.com> wrote:
> 
>> 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

	But it seems like a) way more hassle than editing a wiki directly and b) requires a github account.

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

	I do some stuff with github, but so far directly editing the wiki was less anoying than using the github editors (I use both the github editor and github wiki for other purposes and do not really like them too much)

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

	So I tried that, it appears to be in a middle ground, not as convoluted as I expected it, but also not as "direct" as editing the current wiki. As you promised most of the additional steps are reduced to reading a bit and clicking through. I guess I might even try to add details under such a scheme, but the hurdles would be higher (which might not be a bad thing in itself).

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

	Wasted time mostly in assessing whether I really want to do this multiple times, while editing the wiki feels more immediate (I am ignoring the fact that the github editor is pretty plain and does not offer any help in how to format things nicely/correctly; I assume one gets used to that and the current wiki editor is not that great either)

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

	Well, I am around for some time, but my 10 year younger self, upon seeing the raw .rst .n the github editor, would have just bailed out...

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

	I am not 100% convinced that the LEDE user guides lend themselves to such a continuous text representation.

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

	Ideally the user would not need to deal with the under laying syntax (unless they would want to) a WYSIWYG-Interface for casual edits makes things friendlier to newcomers IMHO.

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

	Given the fun to edit the .rst without any help this kind of checking seems advisable ;)

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

	Just coming from one of the user guides, so admittedly biased and remote from the core documentation; a book would only superficially "bind" the sqm guide (https://lede-project.org/docs/user-guide/sqm) and the qos guide (https://lede-project.org/docs/user-guide/traffic_shaping) into something coherent, they still would not be of one style and scope. But both certainly are better than not having either of them.

Best Regards
	Sebastian

> 
> Cheers,
> 
> Javier
> 
> _______________________________________________
> Lede-dev mailing list
> Lede-dev at lists.infradead.org
> http://lists.infradead.org/mailman/listinfo/lede-dev