> But it seems like a) way more hassle than editing a wiki directly and > b) requires a github account.
The github account is the same as the wiki account, but I do agree that is more hassle mainly because it's not an integrated experience > 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) My focus here is not to deter too much eventual contributions, but boost the amount/quality/easiness of complex contributions that can be made > 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). I don't mind developing a guide if you would find it easier that way [1] > 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) I know the feeling, I wish there was an easier way, which probably with time will be possible to hook, but for now I would just focus on the port and the content. > 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... Agreed > I am not 100% convinced that the LEDE user guides lend themselves to > such a continuous text representation. They don't! I had to edit most of the Quick Start guide to have a single flow. I think however now is more clear on the possibilities offered. > 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. Yep, if you check out [1] people actually recommends using an online visualizer. http://rst.ninjs.org I do agree that it would really cool to have an integrated experience though, although my main focus with this proposal is: * Restructure content as a book, so that it can be exported as singlehtml, pdf, ebook * Gather user feedback on what parts are not clear/need to be fixed through the issue tracking * Ease translations through already available online translation platforms On later stages: * Transform the documentation in a fully fledged book that can serve as a manual for openwrt * Version different API versions depending on the release * Track changes between versions from the user perspective * Document infrastructure stuff like adding buildbot nodes etc. * Document internal software and libraries (unless we generate a new project for each of them to be portable/usable in other distributions/OS) > Given the fun to edit the .rst without any help this kind of checking > seems advisable ;) Agreed, I will add it to the stuff to be done after the decision. My idea for now was: * Add checks in internal links * Add checks to external links * Make sure that the documentation compiles > 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. We would need to edit the content for organizing it as a book. We can easily add a chapter of use cases that can be implemented using OpenWRT/LEDE, and those guides be part of it. I don't hide that it will involve work, but I am confident that the result will be a more manageable guide to master the project possibilities. Javier [1] a base guide: https://socorro.readthedocs.io/en/v8/writingdocs.html _______________________________________________ Lede-dev mailing list Lede-dev@lists.infradead.org http://lists.infradead.org/mailman/listinfo/lede-dev
