Re: [LEDE-DEV] Lede/Openwrt documentation
May I make a late contribution to this thread? As a user and occasional contributor to openwrt and lede I'd like to stress how invaluable the openwrt wiki in its current form is, precisely because it is real hotchpotch. Of course it is unstructured, of course there is redundancy, of course some of it is out of date or plain wrong, but it is still the first place I look when finding out about a new device, or scratching my head trying to configure some new package. I think two separate things are needed. FIrstly, as Alberto argues, core documentation should be written, or at least reviewed, by developers, and kept rigorously up-to-date. But there shouldn't be much of it, otherwise keeping it up to date will involve too much work and simply won't happen. Then secondly, the wiki should be allowed to continue in something like its current anarchic form, to provide a space for device-specific information, tutorials and howtos, projects using openwrt/lede etc. etc. If it is necessary to migrate content, it would be great if the contents of the current openwrt wiki could be preserved, maybe as a read-only "oldwiki". On 17 November 2017 at 01:16, Alberto Bursi wrote: > > > On 16/11/2017 21:42, Javier Domingo Cansino wrote: >> >> Before this thread falls into oblivion, I would like to ask the guys >> on charge of the docs (I think I got the correct emails) for feedback. >> >> The general impression from the list that I have is that there are a >> lot of doubts on if such a hardcore change in documentation will work, >> but the benefits seem to be understood and good. >> >> What if we kept the ToH + project related webpages as wikis, and we >> just moved the guides and howtos to Sphinx based docs? Is this an >> alternative you would prefer? >> >> I really just want to improve the docs, so I would appreciate feedback >> to either discard this proposal entirely or improve it until it's >> accepted. >> >> Cheers, >> >> Javier >> >> >> >> Below a summary of all the feedback: >> >> * Alexander raised an idea about having docs and wiki together, I >> don't see how we would separate that content, but I'm open to >> suggestions. >> >> * Sebastian raised his concerns about deterring casual contributions, >> and I think after the text he agreed it's not as good, but is not that >> bad neither >> >> * Paul suggesting sticking to the wiki because it's easy to edit. If >> possible I would like him to try the flow, as Sebastian did, to see >> how more difficult he finds it. >> >> * Alberto raised the concern on editing content by non-developers and >> fixing links, however after Sebastian's tests I don't know his >> opinion. Supposing of course that I create the appropriate tooling to >> check doc correctness. He also suggested other GIT based wiki. >> >> * Jow (for what I could understand) agreed in the idea of having more >> control over the content, and that the lack of structure in Wikis make >> difficult to find content. > > My opinion on this: we are still talking about window dressing. What is > really needed is that some developer writes and keeps updated core and > developer documentation, whatever is best for developers to do that is good > for me. > > Since they don't seem terribly interested in documentation in any form (only > Jow participated in this thread, and didn't say much beyond his stylistic > preferences and pointing out my mistake), I don't see the point in changing > the status quo. > It would just shuffle around the same text coming from the OpenWRT wiki with > minor updates done while it was in LEDE wiki while not changing the main > issue (and adding his own issues). > > I mean OK, with git/readthedocs we would get a versioned documentation, but > it's not like there is a whole lot of text needing versioning anyway, and > it's easier to do like it was done in the OpenWRT wiki and just state > features available since version X or not available anymore since version Y. > > I'd like to see effort being put into actually creating new documentation > (reverse-engineering stuff or walking around the code) or testing what there > is (both on LEDE and OpenWRT). > > That said, I'm ok with migrating all the wiki into Sphinx apart from project > pages and active content like ToH, table of packages and device-specific > pages (currently only in Openwrt wiki). But I'm still just a volunteer > maintainer, you'd probably need to talk with Ted Hess for the wiki server > access (to install Sphynx in it? I don't know how it is set up exactly) > > -Alberto > > > ___ > Lede-dev mailing list > Lede-dev@lists.infradead.org > http://lists.infradead.org/mailman/listinfo/lede-dev ___ Lede-dev mailing list Lede-dev@lists.infradead.org http://lists.infradead.org/mailman/listinfo/lede-dev
Re: [LEDE-DEV] Lede/Openwrt documentation
On 16/11/2017 21:42, Javier Domingo Cansino wrote: Before this thread falls into oblivion, I would like to ask the guys on charge of the docs (I think I got the correct emails) for feedback. The general impression from the list that I have is that there are a lot of doubts on if such a hardcore change in documentation will work, but the benefits seem to be understood and good. What if we kept the ToH + project related webpages as wikis, and we just moved the guides and howtos to Sphinx based docs? Is this an alternative you would prefer? I really just want to improve the docs, so I would appreciate feedback to either discard this proposal entirely or improve it until it's accepted. Cheers, Javier Below a summary of all the feedback: * Alexander raised an idea about having docs and wiki together, I don't see how we would separate that content, but I'm open to suggestions. * Sebastian raised his concerns about deterring casual contributions, and I think after the text he agreed it's not as good, but is not that bad neither * Paul suggesting sticking to the wiki because it's easy to edit. If possible I would like him to try the flow, as Sebastian did, to see how more difficult he finds it. * Alberto raised the concern on editing content by non-developers and fixing links, however after Sebastian's tests I don't know his opinion. Supposing of course that I create the appropriate tooling to check doc correctness. He also suggested other GIT based wiki. * Jow (for what I could understand) agreed in the idea of having more control over the content, and that the lack of structure in Wikis make difficult to find content. My opinion on this: we are still talking about window dressing. What is really needed is that some developer writes and keeps updated core and developer documentation, whatever is best for developers to do that is good for me. Since they don't seem terribly interested in documentation in any form (only Jow participated in this thread, and didn't say much beyond his stylistic preferences and pointing out my mistake), I don't see the point in changing the status quo. It would just shuffle around the same text coming from the OpenWRT wiki with minor updates done while it was in LEDE wiki while not changing the main issue (and adding his own issues). I mean OK, with git/readthedocs we would get a versioned documentation, but it's not like there is a whole lot of text needing versioning anyway, and it's easier to do like it was done in the OpenWRT wiki and just state features available since version X or not available anymore since version Y. I'd like to see effort being put into actually creating new documentation (reverse-engineering stuff or walking around the code) or testing what there is (both on LEDE and OpenWRT). That said, I'm ok with migrating all the wiki into Sphinx apart from project pages and active content like ToH, table of packages and device-specific pages (currently only in Openwrt wiki). But I'm still just a volunteer maintainer, you'd probably need to talk with Ted Hess for the wiki server access (to install Sphynx in it? I don't know how it is set up exactly) -Alberto ___ Lede-dev mailing list Lede-dev@lists.infradead.org http://lists.infradead.org/mailman/listinfo/lede-dev
Re: [LEDE-DEV] Lede/Openwrt documentation
Before this thread falls into oblivion, I would like to ask the guys on charge of the docs (I think I got the correct emails) for feedback. The general impression from the list that I have is that there are a lot of doubts on if such a hardcore change in documentation will work, but the benefits seem to be understood and good. What if we kept the ToH + project related webpages as wikis, and we just moved the guides and howtos to Sphinx based docs? Is this an alternative you would prefer? I really just want to improve the docs, so I would appreciate feedback to either discard this proposal entirely or improve it until it's accepted. Cheers, Javier Below a summary of all the feedback: * Alexander raised an idea about having docs and wiki together, I don't see how we would separate that content, but I'm open to suggestions. * Sebastian raised his concerns about deterring casual contributions, and I think after the text he agreed it's not as good, but is not that bad neither * Paul suggesting sticking to the wiki because it's easy to edit. If possible I would like him to try the flow, as Sebastian did, to see how more difficult he finds it. * Alberto raised the concern on editing content by non-developers and fixing links, however after Sebastian's tests I don't know his opinion. Supposing of course that I create the appropriate tooling to check doc correctness. He also suggested other GIT based wiki. * Jow (for what I could understand) agreed in the idea of having more control over the content, and that the lack of structure in Wikis make difficult to find content. ___ Lede-dev mailing list Lede-dev@lists.infradead.org http://lists.infradead.org/mailman/listinfo/lede-dev
Re: [LEDE-DEV] Lede/Openwrt documentation
On 13/11/2017 13:11, Jo-Philipp Wich wrote: Hi, The wiki is working for me. it's great to have the ToH. Also the device pages are great. However the wiki is not always completely correct and may be just wrong. It's a wiki, change it! A wiki is always changing. I believe that a wiki is no alternative for a proper, curated documentation. I've also seen many instances where user contributed information was either incomplete or even factually wrong. Yeah, but proper documentation (not tutorials, I mean available commands and their meaning) can only be written by developers. So far on the wiki I've seen (even large) contributions of mostly user-oriented tutorials. Someone did add/change the documentation part, (especially after I asked for it in the github PRs) but I have no idea of how correct that is, or how to test it myself on my hardware. This is why I think having developer-grade and core documentation (like all uci config files for default system) in git is better, so you can enforce contributors to update it with their changes and check that they aren't writing garbage in it. While tutorials, ToH, package table/lists and other user-oriented parts stay in the wiki. I don't think forcing the whole wiki into the readthedocs site is a good idea just as leaving all documentation in the wiki is not great. Another thing I noticed is that some documentation actually seem to have devolved compared to the OpenWrt wiki. I wrote large parts of https://wiki.openwrt.org/doc/uci/network - now compare that with https://lede-project.org/docs/user-guide/network_configuration. Not even did I struggle to find that page in the first place within the LEDE wiki, I also couldn't find any trace of the missing ip rule or route action documentation. Also TOH != documentation. ~ Jo I split that page into separate articles under Network Configuration [1] to improve its readability. Same was done for other articles like the dnsmasq one that was split in DHCP and DNS articles. Information in LEDE wiki is arranged by topic, not by what config file it is in. I think the OpenWRT wiki arrangement for that documentation is not intuitive for everyone but developers, imho. (I also converted instructions to use uci commands instead than manual text editing with vi, as again vi isn't terribly user-friendly and mistakes in manual edits can screw up the configuration file) It seems the mentioned part is missing, it's probably a mistake on my part, I'm sorry for that. I'll have a look this evening to fix it. 1. https://lede-project.org/docs/user-guide/start#basic_configuration -Alberto ___ Lede-dev mailing list Lede-dev@lists.infradead.org http://lists.infradead.org/mailman/listinfo/lede-dev
Re: [LEDE-DEV] Lede/Openwrt documentation
Hi, > The wiki is working for me. it's great to have the ToH. Also the > device pages are great. However the wiki is not always completely > correct and may be just wrong. It's a wiki, change it! A wiki is > always changing. I believe that a wiki is no alternative for a proper, curated documentation. I've also seen many instances where user contributed information was either incomplete or even factually wrong. Another thing I noticed is that some documentation actually seem to have devolved compared to the OpenWrt wiki. I wrote large parts of https://wiki.openwrt.org/doc/uci/network - now compare that with https://lede-project.org/docs/user-guide/network_configuration. Not even did I struggle to find that page in the first place within the LEDE wiki, I also couldn't find any trace of the missing ip rule or route action documentation. Also TOH != documentation. ~ Jo ___ Lede-dev mailing list Lede-dev@lists.infradead.org http://lists.infradead.org/mailman/listinfo/lede-dev
Re: [LEDE-DEV] Lede/Openwrt documentation
> 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
Re: [LEDE-DEV] Lede/Openwrt documentation
Hi Javiet, > On Nov 12, 2017, at 22:24, Javier Domingo Cansino 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
Re: [LEDE-DEV] Lede/Openwrt documentation
> 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
Re: [LEDE-DEV] Lede/Openwrt documentation
Dear Javier, 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. 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). As a casual contributor I do value my time way over any strong "corporate identity" or structure enforcements. Best Regards Sebastian > On Nov 12, 2017, at 16:49, Javier Domingo Cansino wrote: > >> The wiki is working for me. it's great to have the ToH. Also the device >> pages are great. However the wiki is not always completely correct and may >> be just wrong. It's a wiki, change it! A wiki is always changing. > > Just in case, we are not loosing the ToH, it's just that I didn't > implement it for this proposal, as I didn't want to invest more time > without a compromise that it's going somewhere, unless it's required > for a decision. > > The problem is not about correcting a typo, the problem with current > documentation is managing duplicates, outdated information and > restructuring the content for a better UX. Right now, the most helpful > part of the wiki are those presented as guides. > > Also, because of the nature of the project and its complexity, I want > to introduce a code-like flow when adding information, so that we > ensure an overall structure, the way of writing etc. Right now, the > contributions are mainly from the documentation maintainers (tmomas > and bobafetthotmail), the rest are only modifications to the ToH. The > amount of contributions lost by dropping the online editing would be > really low. > > The project is way more than the ToH. The main point why a user would > use a OpenWRT/LEDE, or a developer develop is not because of the > hardware it supports but because of the project's quality, the > software and usecases it supports, extensibility and efficiency. ToH > is important as first step, but after that there is no proper > documentation (although this is improving little by little). > > >> But I still see the case, where I would like to have a documentation which >> is released for a specific version e.g. lede 17.01. I think this >> documentation should cover the base systems [1]. It should be describe >> things in a good and short way. And this documentation is reviewed before >> something changed. So it may be "guaranteed" [2] everything is right. > > This is a future usecase that I haven't mentioned because I would need > to write a huge blogpost to explain all the stuff like that. And we > are not yet in that phase. > >> If it get's to depth into a topic, write it into the wiki. Documentation and >> Wiki would work this way hand in hand. Not erasing each other out. > > There is a doc folder in the repo that no one has updated in a while. > Something clear for me in OpenWRT/LEDE is that developers develop > quality software, but documentation is always left aside. Outdated > documentation is worse than no documentation at all many times. > > I don't see this as a bad thing, people does this as a hobby, and they > are free to contribute what they want. Taking this nature into > account, the best we can do is to remove any documentation from the > sources, and have a documentation team that is in charge of syncing > the docs with the source as much as possible. > > You need to keep track of the changes in the documentation as much as > possible, restructure it many times as content is added etc. Using a > VCS is absolutely required. Please have a look on openstack docs > docs[1]. I had a really interesting talk in the workshops with a > RedHat documentation lead after her talk in the EuroPython 2016[2], > and full control over your documentation is essential. That's why I > discourage the use of a Wiki as a knowledge repository. > > [1] Openstack documentation contribution guide: > https://docs.openstack.org/doc-contrib-guide/index.html > [2] Europython FOSS DOCS 101 talk: > https://ep2016.europython.eu/conference/talks/foss-docs-101-keep-it-simple-present > > --- > >> Add to https://lede-project.org/submitting-patches the instruction that any >> change that would have consequences for documentation, be it for users (e.g. >> UCI), be it for developers: >> - should mention in the commit message that the change affects user and/or >> developer docs (reviewers should check this) >> - should be followed by an update of the wiki once the change has been >> merged (by submitter or someone else) > >> A more formal approach might be that any commit that changes API (developper >> documentation) or UCI (user documentation) must also contain a patch to that >> effect. A means to apply such a patch (and its format) to the wiki would be >> needed. > >> Last, as
Re: [LEDE-DEV] Lede/Openwrt documentation
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
Re: [LEDE-DEV] Lede/Openwrt documentation
> The wiki is working for me. it's great to have the ToH. Also the device pages > are great. However the wiki is not always completely correct and may be just > wrong. It's a wiki, change it! A wiki is always changing. Just in case, we are not loosing the ToH, it's just that I didn't implement it for this proposal, as I didn't want to invest more time without a compromise that it's going somewhere, unless it's required for a decision. The problem is not about correcting a typo, the problem with current documentation is managing duplicates, outdated information and restructuring the content for a better UX. Right now, the most helpful part of the wiki are those presented as guides. Also, because of the nature of the project and its complexity, I want to introduce a code-like flow when adding information, so that we ensure an overall structure, the way of writing etc. Right now, the contributions are mainly from the documentation maintainers (tmomas and bobafetthotmail), the rest are only modifications to the ToH. The amount of contributions lost by dropping the online editing would be really low. The project is way more than the ToH. The main point why a user would use a OpenWRT/LEDE, or a developer develop is not because of the hardware it supports but because of the project's quality, the software and usecases it supports, extensibility and efficiency. ToH is important as first step, but after that there is no proper documentation (although this is improving little by little). > But I still see the case, where I would like to have a documentation which is > released for a specific version e.g. lede 17.01. I think this documentation > should cover the base systems [1]. It should be describe things in a good and > short way. And this documentation is reviewed before something changed. So it > may be "guaranteed" [2] everything is right. This is a future usecase that I haven't mentioned because I would need to write a huge blogpost to explain all the stuff like that. And we are not yet in that phase. > If it get's to depth into a topic, write it into the wiki. Documentation and > Wiki would work this way hand in hand. Not erasing each other out. There is a doc folder in the repo that no one has updated in a while. Something clear for me in OpenWRT/LEDE is that developers develop quality software, but documentation is always left aside. Outdated documentation is worse than no documentation at all many times. I don't see this as a bad thing, people does this as a hobby, and they are free to contribute what they want. Taking this nature into account, the best we can do is to remove any documentation from the sources, and have a documentation team that is in charge of syncing the docs with the source as much as possible. You need to keep track of the changes in the documentation as much as possible, restructure it many times as content is added etc. Using a VCS is absolutely required. Please have a look on openstack docs docs[1]. I had a really interesting talk in the workshops with a RedHat documentation lead after her talk in the EuroPython 2016[2], and full control over your documentation is essential. That's why I discourage the use of a Wiki as a knowledge repository. [1] Openstack documentation contribution guide: https://docs.openstack.org/doc-contrib-guide/index.html [2] Europython FOSS DOCS 101 talk: https://ep2016.europython.eu/conference/talks/foss-docs-101-keep-it-simple-present --- > Add to https://lede-project.org/submitting-patches the instruction that any > change that would have consequences for documentation, be it for users (e.g. > UCI), be it for developers: > - should mention in the commit message that the change affects user and/or > developer docs (reviewers should check this) > - should be followed by an update of the wiki once the change has been merged > (by submitter or someone else) > A more formal approach might be that any commit that changes API (developper > documentation) or UCI (user documentation) must also contain a patch to that > effect. A means to apply such a patch (and its format) to the wiki would be > needed. > Last, assuming we maintain one set of user docs for all branches, the docs > should, in case the branch matters, document those differences. > The developers documentation would presumably just need to document the > master branch. Developers are not going to write all documentation, if they wanted to they would have done this time ago. And from my personal perspective, being a good developer doesn't mean you are a good documentation writer. I think enforcing something like that would lower the amount of contributions per developer, and would deter possible contributions. In an small company you are supposed to do everything, but in really big companies, developers just document their code for maintenance purposes, and you have specialized teams creating enduser documentation. Developers don't need to be writers. --- Wikis are
Re: [LEDE-DEV] Lede/Openwrt documentation
M2C: Wiki's are wonderful for documentation purposes as it allows anyone to attribute without much difficulty. But how to ensure that the documentation follows project code changes ? Add to https://lede-project.org/submitting-patches the instruction that any change that would have consequences for documentation, be it for users (e.g. UCI), be it for developers: - should mention in the commit message that the change affects user and/or developer docs (reviewers should check this) - should be followed by an update of the wiki once the change has been merged (by submitter or someone else) A more formal approach might be that any commit that changes API (developper documentation) or UCI (user documentation) must also contain a patch to that effect. A means to apply such a patch (and its format) to the wiki would be needed. Last, assuming we maintain one set of user docs for all branches, the docs should, in case the branch matters, document those differences. The developers documentation would presumably just need to document the master branch. Paul > Op 12 nov. 2017, om 02:32 heeft Alexander Couzens het > volgende geschreven: > > Here is my IMHO: > > wiki = OpenWrt and LEDE > > The wiki is working for me. it's great to have the ToH. Also the device > pages are great. However the wiki is not always completely correct and > may be just wrong. It's a wiki, change it! A wiki is always changing. > > But I still see the case, where I would like to have a documentation > which is released for a specific version e.g. lede 17.01. > I think this documentation should cover the base systems [1]. It should > be describe things in a good and short way. > And this documentation is reviewed before something changed. So it may > be "guaranteed" [2] everything is right. > > If it get's to depth into a topic, write it into the wiki. > Documentation and Wiki would work this way hand in hand. Not erasing > each other out. > > best > lynxis > > ps. thanks to everybody who contributed to the wiki and documentation! > > [1] what base system means in this context is to be defined. > [2] there is no guarantee ;) > > -- > Alexander Couzens > > mail: lyn...@fe80.eu > jabber: lyn...@fe80.eu > mobile: +4915123277221 > gpg: 390D CF78 8BF9 AA50 4F8F F1E2 C29E 9DA6 A0DF 8604 > ___ > Lede-dev mailing list > Lede-dev@lists.infradead.org > http://lists.infradead.org/mailman/listinfo/lede-dev ___ Lede-dev mailing list Lede-dev@lists.infradead.org http://lists.infradead.org/mailman/listinfo/lede-dev
Re: [LEDE-DEV] Lede/Openwrt documentation
Here is my IMHO: wiki = OpenWrt and LEDE The wiki is working for me. it's great to have the ToH. Also the device pages are great. However the wiki is not always completely correct and may be just wrong. It's a wiki, change it! A wiki is always changing. But I still see the case, where I would like to have a documentation which is released for a specific version e.g. lede 17.01. I think this documentation should cover the base systems [1]. It should be describe things in a good and short way. And this documentation is reviewed before something changed. So it may be "guaranteed" [2] everything is right. If it get's to depth into a topic, write it into the wiki. Documentation and Wiki would work this way hand in hand. Not erasing each other out. best lynxis ps. thanks to everybody who contributed to the wiki and documentation! [1] what base system means in this context is to be defined. [2] there is no guarantee ;) -- Alexander Couzens mail: lyn...@fe80.eu jabber: lyn...@fe80.eu mobile: +4915123277221 gpg: 390D CF78 8BF9 AA50 4F8F F1E2 C29E 9DA6 A0DF 8604 pgpY9wcBKmUfK.pgp Description: OpenPGP digital signature ___ Lede-dev mailing list Lede-dev@lists.infradead.org http://lists.infradead.org/mailman/listinfo/lede-dev
Re: [LEDE-DEV] Lede/Openwrt documentation
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 ___ Lede-dev mailing list Lede-dev@lists.infradead.org http://lists.infradead.org/mailman/listinfo/lede-dev
Re: [LEDE-DEV] Lede/Openwrt documentation
Hello, I haven't been able to open a computer past week, so this is running slower than I thought. I have made it available in https://lede.readthedocs.io/en/latest/ and for now it's just the start + about page. I will keep adding pages until I cover the basics, and send an email when it's more readable. If someone wants to collaborate, all the work is happening in https://github.com/txomon/lede-docs, and consists on moving pages from /wiki/pages/ to / and converting the syntax manually, as all the tools I have seen are not working properly. I have created a converter within wiki/ folder, but because it would require too much work for the results (links would be broken anyway), I have left the development of it. There is also available a php script to convert from dokuwiki to mediawiki, and then you can use pandoc to convert from mediawiki to restructured text. Cheers, Javier ___ Lede-dev mailing list Lede-dev@lists.infradead.org http://lists.infradead.org/mailman/listinfo/lede-dev
Re: [LEDE-DEV] Lede/Openwrt documentation
> To clarify: the "convert dokuwiki to git" thing I was talking about is > just a technical possibility for merging the OpenWrt wiki and the LEDE > wiki. I was certainly not suggesting to switch to a completely new system > for the wiki: I think it's fine as it is for most of the documentation. Yes, it just gave me the idea. > I think you are right, we can do markdown for now and later change > some pages if required,... Although it doesn't have ToC primitives, > etc. I must take back this. I have been juggling with the program to convert between different markups, and sadly realised that it's not going to be possible to have cross references etc. using markdown alone... Also, I had a look on the amount of content of the wiki, and counted around 400+ entries.. not including pkgdata or toh content. I need to devise a way to make the migration properly. For now, I believe that because of all the corner cases on linking etc. I will just migrate by hand using a couple of markup conversion scripts + manual editing. If someone is interested in helping with this, please don't hesitate. I will see how much I can do in the next few days, Javier -- Javier Domingo Cansino ___ Lede-dev mailing list Lede-dev@lists.infradead.org http://lists.infradead.org/mailman/listinfo/lede-dev
Re: [LEDE-DEV] Lede/Openwrt documentation
Hi, On 27-10-17, Javier Domingo Cansino wrote: > > This problem is well-known [1,2] and can be solved by having access to a > > common ancestor between the two versions. A possible way to do this would > > be to convert each wiki to a git repository [3], merge the two histories > > using git, and then convert back the git repository to a dokuwiki > > structure. It sounds tedious but feasible. > > As it looks like there are no clear decisions, I would like to propose > the following changes. To clarify: the "convert dokuwiki to git" thing I was talking about is just a technical possibility for merging the OpenWrt wiki and the LEDE wiki. I was certainly not suggesting to switch to a completely new system for the wiki: I think it's fine as it is for most of the documentation. > Git backed documentation: > * It's easier to have all the content at a glance sorted in folders > to help structure the documentation > * You can move content between pages easier > > Use github as a place to host the document repository: > * There are buildhooks from services integrated, such as github pages > or readthedocs that make it transparent to collaborate > * Users can provide feedback through issues on missing docs, giving > tips to contributors to see what areas can be improved > * Discussions about documental structure happen openly, easing burden > on people maintaining documentation by having an specific pipe > everything goes through > * Contributions can be reviewed or automatically contributed if diff > < 100 lines (I can do a simple bot for that) > > Integrate existing openwrt docs inside lede structure. > * Having an structured documentation helps user know where to look > for the content > * Makes easier to spot a place to write your contribution at > * It is more user / dev-newbie friendly > > Switch to sphinx > * Most of the times there is no clue on where to place the > documentation, so you create a new wiki page, this leads to duplicate > information > * Can generate HTML Single page, pdf, epub, etc. Although the usual > one is the multipage HTML > * Can be hosted in readthedocs and integrated with github so that > every deployment is automatic > * Can tag versions, so in the event we finally reach a good > documentation, users can browse different docs for each version > * It's industry standard for project documentation. Not only about > documenting python > * It has good to go skins that are proven to be easy to read > * More complete syntax (if something like that would be required > > Drawbacks I see: > * Contributions in the wiki are instant, here they would have a > proper process to review. > * There is a migration effort to be done, greater than just merging > docs in the same place > > I volunteer however to setup today an example with the current lede > docs in sphinx, so that you can see the look and feel I am speaking > about. > > Also, openwrt.readthedocs.org is taken but if we were to make official > this proposal, I would contact the current owner or rtd people to get > it transferred. > > Cheers, signature.asc Description: PGP signature ___ Lede-dev mailing list Lede-dev@lists.infradead.org http://lists.infradead.org/mailman/listinfo/lede-dev
Re: [LEDE-DEV] Lede/Openwrt documentation
Hi Alberto, On 27-10-17, John Norton wrote: > On 27/10/2017 10:46, Baptiste Jonglez wrote: > >On 24-10-17, John Norton wrote: > >>On 24/10/2017 18:02, Javier Domingo Cansino wrote: > >>Imho (what I would do) is just migrate current LEDE wiki content in OpenWRT > >>wiki, > >>while current OpenWRT stuff is either obsoleted (where it is replaced by the > >>LEDE wiki articles) or moved to suit the same general structure of LEDE > >>wiki. > >Don't underestimate the amount of contributions made to the OpenWrt wiki > >during the LEDE/OpenWrt split. Old habits are hard to break :) > > > > Don't overestimate the amount of content in LEDE wiki. It's mostly core > documentation. Don't get me wrong: there is no question that the LEDE wiki has improved quite a lot during the split, both in content and organisation. And given the amount of effort that went into it (especially the ToH), it only makes sense to use it as the "authoritative" source when merging the two wikis. What I was saying is simply this: out of habit, some people (including myself) have contributed content to the OpenWrt wiki instead of the LEDE wiki. Just look at this for example: https://wiki.openwrt.org/start?do=recent https://wiki.openwrt.org/doc/uci/wireless?do=revisions https://wiki.openwrt.org/doc/devel/packages?do=revisions > LEDE wiki can be moved over as-is, its articles more or less directly > obsoleting their analogue in the OpenWRT wiki after a quick read and source > modification check after the merge. > > Bulk of content in OpenWRT wiki does not have an analogue in LEDE wiki, so > that can just be re-arranged without modification (for now). Your proposed method looks good, I am just afraid that the "quick read" may not be that quick given the above considerations (to ensure that no relevant content is lost). Baptiste signature.asc Description: PGP signature ___ Lede-dev mailing list Lede-dev@lists.infradead.org http://lists.infradead.org/mailman/listinfo/lede-dev
Re: [LEDE-DEV] Lede/Openwrt documentation
> It seems that there was a bit of confusion. What you quote here is > from me, not from Javier. Also, it's from a different thread [1], in > which I indeed proposed a new system from the developer documentation > (only). > > The current thread is about how to merge the LEDE wiki and the OpenWrt > wiki. > Or at least, that was the initial discussion. I indeed mixed that up as much as possible. Sorry for that! Thomas ___ Lede-dev mailing list Lede-dev@lists.infradead.org http://lists.infradead.org/mailman/listinfo/lede-dev
Re: [LEDE-DEV] Lede/Openwrt documentation
Hi Thomas, On 27-10-17, Thomas Endt wrote: > That's contrary to your statements in the start posting: > > > [...] documentation targeted at hackers, contributors, and would-be > > developers. > > [...] RFC proposal of a new developer documentation > > Links [1] [2] [3] > > [...] more focused scope: the scope is explicitly limited to developer > > documentation. > > [...] this new doc would serve as a detailed and up-to-date reference for > > OpenWrt internals, while the wiki would still be extremely useful for > > user-oriented documentation It seems that there was a bit of confusion. What you quote here is from me, not from Javier. Also, it's from a different thread [1], in which I indeed proposed a new system from the developer documentation (only). The current thread is about how to merge the LEDE wiki and the OpenWrt wiki. Or at least, that was the initial discussion. Baptiste [1] http://lists.infradead.org/pipermail/lede-dev/2017-October/009530.html signature.asc Description: PGP signature ___ Lede-dev mailing list Lede-dev@lists.infradead.org http://lists.infradead.org/mailman/listinfo/lede-dev
Re: [LEDE-DEV] Lede/Openwrt documentation
> > - We are talking about the developer pages only, or about the > complete > > content? > > Everything That's contrary to your statements in the start posting: > [...] documentation targeted at hackers, contributors, and would-be > developers. > [...] RFC proposal of a new developer documentation > Links [1] [2] [3] > [...] more focused scope: the scope is explicitly limited to developer > documentation. > [...] this new doc would serve as a detailed and up-to-date reference for > OpenWrt internals, while the wiki would still be extremely useful for > user-oriented documentation Why is this contrary? Because "Everything" includes everything in here: https://wiki.openwrt.org/toh/?do=index and I guess you don't really want to have each and every little change to the devicepages (/toh/yourbrand/yourmodel) go through git. Don't get me wrong, I just want to clarify the scope of your proposal. You can and will get everything you want, because I support your proposal to lift the developer docs to a new level of quality. Keep you posted. Thomas ___ Lede-dev mailing list Lede-dev@lists.infradead.org http://lists.infradead.org/mailman/listinfo/lede-dev
Re: [LEDE-DEV] Lede/Openwrt documentation
> > The wiki currently hosts and renders tables on the basis of data > > acquired and stored in a database. > > The table of packages and table of hardware. They are searchable and > > can be filtered. > > The table of hardware has a template system to let people add new > > devices to the "hardware database". > > https://lede-project.org/meta/create_new_dataentry_page > > Is there a way to do something like that with this new system? > > We can setup a file to be copied and filled, and people would just fill > it. What is the objective of the database? What uses does it have? https://lede-project.org/toh/start The ToH (Table of Hardware) lists devices which are supported by OpenWrt (and quite some that are not supported; remainders of old times). It comes in different views, showing different columns, paying respect to limited horizontal screen space. - All views: https://lede-project.org/toh/views/start - View for selecting a new device to be bought, filtered for supported devices which have >4MB flash + >32MB RAM -> https://lede-project.org/toh/views/toh_available_864 - View for downloading firmware: https://lede-project.org/toh/views/toh_fwdownload Just having a "file that people fill" seems to go in the direction of having a static table. That's not what we want. Filtering for certain data is a mandatory feature. This whole ToH thing is worth a discussion on its own. Thomas ___ Lede-dev mailing list Lede-dev@lists.infradead.org http://lists.infradead.org/mailman/listinfo/lede-dev
Re: [LEDE-DEV] Lede/Openwrt documentation
> Just to get a clear picture: > - We are talking about the LEDE wiki pages or the OpenWrt wiki pages, or > both? http://lists.infradead.org/pipermail/lede-dev/2017-October/009564.html > - We are talking about the developer pages only, or about the complete > content? Everything -- Javier Domingo Cansino ___ Lede-dev mailing list Lede-dev@lists.infradead.org http://lists.infradead.org/mailman/listinfo/lede-dev
Re: [LEDE-DEV] Lede/Openwrt documentation
> If you want to use the GH editor, I'd go with markdown. For markdown, > the GH web editor has syntax highlighting and and (more important) a > usable preview mode, for RST all you get is a very simple plain text editor. I think you are right, we can do markdown for now and later change some pages if required,... Although it doesn't have ToC primitives, etc. http://blog.readthedocs.com/adding-markdown-support/http://blog.readthedocs.com/adding-markdown-support/ It should be ok for most of the use cases though ___ Lede-dev mailing list Lede-dev@lists.infradead.org http://lists.infradead.org/mailman/listinfo/lede-dev
Re: [LEDE-DEV] Lede/Openwrt documentation
> > What exactly do you need? All wiki pages? Including history? > > Will look into this this evening. We will find an easy way. > > Someone mentioned there were private pages, but if possible, I would > create a git repo, commit all the content and upload it to github. I > can work on a proper history rewrite if we want to keep history, but I > would just focus on the latest version, rewriting history later is just > git work. Just to get a clear picture: - We are talking about the LEDE wiki pages or the OpenWrt wiki pages, or both? - We are talking about the developer pages only, or about the complete content? Thomas ___ Lede-dev mailing list Lede-dev@lists.infradead.org http://lists.infradead.org/mailman/listinfo/lede-dev
Re: [LEDE-DEV] Lede/Openwrt documentation
Hello everybody, here my 2 cents: > This system would work through PRs in github, and the user could link > "Edit this file in github", which would direct him to the file, and > there he would be able to click on "Fork and edit", and then submit a > pull request. From my experience, this works pretty well: Click on the "edit" button on the web site, get asked for github credentials, get dumped into the github editor for the page (as far as I remember GH even automatically forks the repository if you don't have a fork already), and if you save the file a PR is generated. If someone wnats to see an example in action, I've set up a system like this (based on Github Pages, with markdown as documentation format because that is what GH pages/Jekyll uses) at http://cfw.ftcommunity.de. > Also, if desired I can configure sphinx with markdown support, so that > Markdown can be used to write docs, however my experience is that you > will end up turning everything into RST, therefore I would just add a > link to http://rst.ninjs.org/ or http://rst.aaroniles.net/ so that the > user can look on it. If you want to use the GH editor, I'd go with markdown. For markdown, the GH web editor has syntax highlighting and and (more important) a usable preview mode, for RST all you get is a very simple plain text editor. best regards, Richard ___ Lede-dev mailing list Lede-dev@lists.infradead.org http://lists.infradead.org/mailman/listinfo/lede-dev
Re: [LEDE-DEV] Lede/Openwrt documentation
I will suppose all the proposals are accepted when answering > I see this can be a good way forward, but I have some questions. > > I still think user-level documentation must have a decent wiki-like editor > in the browser, because github's editor > sucks big way, and isn't suited for proper formatting and similar. I'm not > that happy with docuwiki's editor (current editor) either. > Does your proposed system have something like that? I'm afraid there is no online editing as in dokuwiki. This system would work through PRs in github, and the user could link "Edit this file in github", which would direct him to the file, and there he would be able to click on "Fork and edit", and then submit a pull request. The process is not optimal for really sparse contributions, but I believe it can help to maintain documental integrity. Also, if desired I can configure sphinx with markdown support, so that Markdown can be used to write docs, however my experience is that you will end up turning everything into RST, therefore I would just add a link to http://rst.ninjs.org/ or http://rst.aaroniles.net/ so that the user can look on it. However, I have doubts on the throughput of contributions there are. > > The wiki currently hosts and renders tables on the basis of data acquired > and stored in a database. > The table of packages and table of hardware. They are searchable and can be > filtered. > The table of hardware has a template system to let people add new devices to > the "hardware database". > https://lede-project.org/meta/create_new_dataentry_page > Is there a way to do something like that with this new system? We can setup a file to be copied and filled, and people would just fill it. What is the objective of the database? What uses does it have? Anyway, if we did want to have something fed from a DB, we can always create an extension that renders such thing. I have done similar work to render different things, but I would try to avoid it. Unless that database is linked somewhere, we could also create a custom syntax in an extension to actually render in different ways all the usages of such data (similar to how ToC, TODO lists, etc. work). > > Docuwiki allows people to translate the same pages to other languages, and > keeps track of what pages have an out-of-sync translation. > There are at least a couple asian translators > (chinese/japanese/korean/whatever) and a russian guy that did some work > there. Sphinx supports gettext, so virtually everything could be translated. If we integrated it with launchpad, transifex or zanata to name a few, we would be able to have translations in any language, falling back to english, and we would be able to have proper language coverage statistics. Also, because these places sometimes have translators roaming through other opensource projects, we may end up getting better coverage. > What exactly do you need? All wiki pages? Including history? > Will look into this this evening. We will find an easy way. Someone mentioned there were private pages, but if possible, I would create a git repo, commit all the content and upload it to github. I can work on a proper history rewrite if we want to keep history, but I would just focus on the latest version, rewriting history later is just git work. Cheers, -- Javier Domingo Cansino ___ Lede-dev mailing list Lede-dev@lists.infradead.org http://lists.infradead.org/mailman/listinfo/lede-dev
Re: [LEDE-DEV] Lede/Openwrt documentation
Am 27. Oktober 2017 15:14:19 MESZ schrieb Javier Domingo Cansino : >> And yes, I'm talking of things I can/will do personally. > >Is there any way to access all the wiki files? I am doing it manually >and its turning out to be quite tedious... =) What exactly do you need? All wiki pages? Including history? Will look into this this evening. We will find an easy way. ___ Lede-dev mailing list Lede-dev@lists.infradead.org http://lists.infradead.org/mailman/listinfo/lede-dev
Re: [LEDE-DEV] Lede/Openwrt documentation
On 27/10/2017 15:14, Javier Domingo Cansino wrote: And yes, I'm talking of things I can/will do personally. Is there any way to access all the wiki files? I am doing it manually and its turning out to be quite tedious... =) afaik the only way is accessing the server itself over ssh. There all wiki pages are stored as plaintext (not as html). -Alberto ___ Lede-dev mailing list Lede-dev@lists.infradead.org http://lists.infradead.org/mailman/listinfo/lede-dev
Re: [LEDE-DEV] Lede/Openwrt documentation
On 27/10/2017 13:58, Javier Domingo Cansino wrote: This problem is well-known [1,2] and can be solved by having access to a common ancestor between the two versions. A possible way to do this would be to convert each wiki to a git repository [3], merge the two histories using git, and then convert back the git repository to a dokuwiki structure. It sounds tedious but feasible. As it looks like there are no clear decisions, I would like to propose the following changes. Git backed documentation: * It's easier to have all the content at a glance sorted in folders to help structure the documentation * You can move content between pages easier Use github as a place to host the document repository: * There are buildhooks from services integrated, such as github pages or readthedocs that make it transparent to collaborate * Users can provide feedback through issues on missing docs, giving tips to contributors to see what areas can be improved * Discussions about documental structure happen openly, easing burden on people maintaining documentation by having an specific pipe everything goes through * Contributions can be reviewed or automatically contributed if diff < 100 lines (I can do a simple bot for that) Integrate existing openwrt docs inside lede structure. * Having an structured documentation helps user know where to look for the content * Makes easier to spot a place to write your contribution at * It is more user / dev-newbie friendly Switch to sphinx * Most of the times there is no clue on where to place the documentation, so you create a new wiki page, this leads to duplicate information * Can generate HTML Single page, pdf, epub, etc. Although the usual one is the multipage HTML * Can be hosted in readthedocs and integrated with github so that every deployment is automatic * Can tag versions, so in the event we finally reach a good documentation, users can browse different docs for each version * It's industry standard for project documentation. Not only about documenting python * It has good to go skins that are proven to be easy to read * More complete syntax (if something like that would be required Drawbacks I see: * Contributions in the wiki are instant, here they would have a proper process to review. * There is a migration effort to be done, greater than just merging docs in the same place I volunteer however to setup today an example with the current lede docs in sphinx, so that you can see the look and feel I am speaking about. Also, openwrt.readthedocs.org is taken but if we were to make official this proposal, I would contact the current owner or rtd people to get it transferred. Cheers, I see this can be a good way forward, but I have some questions. I still think user-level documentation must have a decent wiki-like editor in the browser, because github's editor sucks big way, and isn't suited for proper formatting and similar. I'm not that happy with docuwiki's editor (current editor) either. Does your proposed system have something like that? The wiki currently hosts and renders tables on the basis of data acquired and stored in a database. The table of packages and table of hardware. They are searchable and can be filtered. The table of hardware has a template system to let people add new devices to the "hardware database". https://lede-project.org/meta/create_new_dataentry_page Is there a way to do something like that with this new system? Docuwiki allows people to translate the same pages to other languages, and keeps track of what pages have an out-of-sync translation. There are at least a couple asian translators (chinese/japanese/korean/whatever) and a russian guy that did some work there. I mean I'm not a fan of the docuwiki, it's a brick and lacks flexibility, but it is still better than plaintext. -Alberto ___ Lede-dev mailing list Lede-dev@lists.infradead.org http://lists.infradead.org/mailman/listinfo/lede-dev
Re: [LEDE-DEV] Lede/Openwrt documentation
> And yes, I'm talking of things I can/will do personally. Is there any way to access all the wiki files? I am doing it manually and its turning out to be quite tedious... =) -- Javier Domingo Cansino ___ Lede-dev mailing list Lede-dev@lists.infradead.org http://lists.infradead.org/mailman/listinfo/lede-dev
Re: [LEDE-DEV] Lede/Openwrt documentation
On 27/10/2017 10:46, Baptiste Jonglez wrote: Hi, On 24-10-17, John Norton wrote: On 24/10/2017 18:02, Javier Domingo Cansino wrote: Imho (what I would do) is just migrate current LEDE wiki content in OpenWRT wiki, while current OpenWRT stuff is either obsoleted (where it is replaced by the LEDE wiki articles) or moved to suit the same general structure of LEDE wiki. Don't underestimate the amount of contributions made to the OpenWrt wiki during the LEDE/OpenWrt split. Old habits are hard to break :) Don't overestimate the amount of content in LEDE wiki. It's mostly core documentation. LEDE wiki can be moved over as-is, its articles more or less directly obsoleting their analogue in the OpenWRT wiki after a quick read and source modification check after the merge. Bulk of content in OpenWRT wiki does not have an analogue in LEDE wiki, so that can just be re-arranged without modification (for now). And yes, I'm talking of things I can/will do personally. -Alberto ___ Lede-dev mailing list Lede-dev@lists.infradead.org http://lists.infradead.org/mailman/listinfo/lede-dev
Re: [LEDE-DEV] Lede/Openwrt documentation
> This problem is well-known [1,2] and can be solved by having access to a > common ancestor between the two versions. A possible way to do this would > be to convert each wiki to a git repository [3], merge the two histories > using git, and then convert back the git repository to a dokuwiki > structure. It sounds tedious but feasible. As it looks like there are no clear decisions, I would like to propose the following changes. Git backed documentation: * It's easier to have all the content at a glance sorted in folders to help structure the documentation * You can move content between pages easier Use github as a place to host the document repository: * There are buildhooks from services integrated, such as github pages or readthedocs that make it transparent to collaborate * Users can provide feedback through issues on missing docs, giving tips to contributors to see what areas can be improved * Discussions about documental structure happen openly, easing burden on people maintaining documentation by having an specific pipe everything goes through * Contributions can be reviewed or automatically contributed if diff < 100 lines (I can do a simple bot for that) Integrate existing openwrt docs inside lede structure. * Having an structured documentation helps user know where to look for the content * Makes easier to spot a place to write your contribution at * It is more user / dev-newbie friendly Switch to sphinx * Most of the times there is no clue on where to place the documentation, so you create a new wiki page, this leads to duplicate information * Can generate HTML Single page, pdf, epub, etc. Although the usual one is the multipage HTML * Can be hosted in readthedocs and integrated with github so that every deployment is automatic * Can tag versions, so in the event we finally reach a good documentation, users can browse different docs for each version * It's industry standard for project documentation. Not only about documenting python * It has good to go skins that are proven to be easy to read * More complete syntax (if something like that would be required Drawbacks I see: * Contributions in the wiki are instant, here they would have a proper process to review. * There is a migration effort to be done, greater than just merging docs in the same place I volunteer however to setup today an example with the current lede docs in sphinx, so that you can see the look and feel I am speaking about. Also, openwrt.readthedocs.org is taken but if we were to make official this proposal, I would contact the current owner or rtd people to get it transferred. Cheers, -- Javier Domingo Cansino ___ Lede-dev mailing list Lede-dev@lists.infradead.org http://lists.infradead.org/mailman/listinfo/lede-dev
Re: [LEDE-DEV] Lede/Openwrt documentation
Hi, On 24-10-17, John Norton wrote: > On 24/10/2017 18:02, Javier Domingo Cansino wrote: > Imho (what I would do) is just migrate current LEDE wiki content in OpenWRT > wiki, > while current OpenWRT stuff is either obsoleted (where it is replaced by the > LEDE wiki articles) or moved to suit the same general structure of LEDE > wiki. Don't underestimate the amount of contributions made to the OpenWrt wiki during the LEDE/OpenWrt split. Old habits are hard to break :) Just diff'ing the dokuwiki files on the two servers would not be very useful, because there is no way to know if a chunk has been removed on one side (e.g. LEDE) or added on the other side (e.g. OpenWrt). This problem is well-known [1,2] and can be solved by having access to a common ancestor between the two versions. A possible way to do this would be to convert each wiki to a git repository [3], merge the two histories using git, and then convert back the git repository to a dokuwiki structure. It sounds tedious but feasible. Baptiste [1] http://www.cis.upenn.edu/~bcpierce/unison/download/releases/stable/unison-manual.html#merge [2] https://en.wikipedia.org/wiki/Merge_(version_control)#Three-way_merge [3] https://github.com/hoxu/dokuwiki2git signature.asc Description: PGP signature ___ Lede-dev mailing list Lede-dev@lists.infradead.org http://lists.infradead.org/mailman/listinfo/lede-dev
Re: [LEDE-DEV] Lede/Openwrt documentation
> Depends on the direction we will be moving, see above. If I can give my opinion, having little training on openwrt-lede code base specifics, I find the LEDE docs better organized. My contributions were around 2 years ago, and focused on documenting the libs that are used in the core of lede-openwrt, libubox, ubus, etc. >From a developer perspective, I like very much how the LEDE documents have a walkthrough on developing your own apps, testing, packaging etc. Also, I find easier to read the LEDE docs, probably because of the openwrt skin, and because they were organized altogether from previous experience with the openwrt wiki. Cheers, -- Javier ___ Lede-dev mailing list Lede-dev@lists.infradead.org http://lists.infradead.org/mailman/listinfo/lede-dev
Re: [LEDE-DEV] Lede/Openwrt documentation
> -Ursprüngliche Nachricht- > Von: Lede-dev [mailto:lede-dev-boun...@lists.infradead.org] Im Auftrag > von John Norton > Gesendet: Dienstag, 24. Oktober 2017 18:20 > An: lede-dev@lists.infradead.org > Betreff: Re: [LEDE-DEV] Lede/Openwrt documentation > > > > On 24/10/2017 18:02, Javier Domingo Cansino wrote: > > Hello, > > > > I have been reviewing email on the archive about what will happen > with > > openwrt/lede documentation on the remerge, and I couldn't reach any > > conclusion. Would mind anyone clarifying? > > > > Cheers, > > > > Javier > > > > ___ > > Lede-dev mailing list > > Lede-dev@lists.infradead.org > > http://lists.infradead.org/mailman/listinfo/lede-dev > > Afaik it's not decided what will happen to it until they have finished > the repo/code merging. > > Imho (what I would do) is just migrate current LEDE wiki content in > OpenWRT wiki, Question @devs: Which way will we be moving? From LEDE server to OpenWrt server or vice versa? > while current OpenWRT stuff is either obsoleted (where it > is replaced by the LEDE wiki articles) or moved to suit the same > general structure of LEDE wiki. Sounds easier than it is / will be, or maybe I'm thinking too complicated. Alberto, I'd really appreciate having you in the wiki-admin team to accomplish the wiki merge. > Since both use the same wiki framework (mediawiki) it should be easy. It's dokuwiki for both. > If this happens I'll probably need ssh access and sudo rights for the > OpenWRT wiki server and an admin account in the wiki software, Depends on the direction we will be moving, see above. Regards, Thomas ___ Lede-dev mailing list Lede-dev@lists.infradead.org http://lists.infradead.org/mailman/listinfo/lede-dev
Re: [LEDE-DEV] Lede/Openwrt documentation
On 24/10/2017 18:02, Javier Domingo Cansino wrote: Hello, I have been reviewing email on the archive about what will happen with openwrt/lede documentation on the remerge, and I couldn't reach any conclusion. Would mind anyone clarifying? Cheers, Javier ___ Lede-dev mailing list Lede-dev@lists.infradead.org http://lists.infradead.org/mailman/listinfo/lede-dev Afaik it's not decided what will happen to it until they have finished the repo/code merging. Imho (what I would do) is just migrate current LEDE wiki content in OpenWRT wiki, while current OpenWRT stuff is either obsoleted (where it is replaced by the LEDE wiki articles) or moved to suit the same general structure of LEDE wiki. Since both use the same wiki framework (mediawiki) it should be easy. If this happens I'll probably need ssh access and sudo rights for the OpenWRT wiki server and an admin account in the wiki software, so I can port over (and maintain if needed) the script that currently indexes packages to create the package indexes and package tables in the LEDE wiki. -Alberto ___ Lede-dev mailing list Lede-dev@lists.infradead.org http://lists.infradead.org/mailman/listinfo/lede-dev
[LEDE-DEV] Lede/Openwrt documentation
Hello, I have been reviewing email on the archive about what will happen with openwrt/lede documentation on the remerge, and I couldn't reach any conclusion. Would mind anyone clarifying? Cheers, Javier ___ Lede-dev mailing list Lede-dev@lists.infradead.org http://lists.infradead.org/mailman/listinfo/lede-dev
