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