> 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 great for spontaneous edits. But that's IMO where the good things end. As a user, I don't really care about the shape of the documentation as long as I have all the information I need easily accesible, and with a clear structure that helps me to understand the project. As a documentation maintainer, git-based book-like documentation helps to have a single documental line, and making it easier to: * Avoid duplicates * Restructure documentation to add new sections * Do a bulk edit for an scheduled change (for example, a release) * Have control over the contents, enforcing prose, guidelines, and phrasing to unify the content I can go on with why a proper documentation engine is more adequate for our use case, but just think that the number of users contributing to the docs are mainly the documentation maintainers, having 1 or 2 changes a day done by other users. We don't have a huge contributor base, and we are not documenting really different things, like Archlinux or Gentoo could be, but rather one thing, OpenWRT/LEDE and everything about it. The main reason why I am pushing for a change from an unstructured documentation to an structured one is because as a user I have always found impossible to have all the information at a glance, documentation was many times duplicated and outdated. Then, I moved into contributing, and I just found so discouraging to make big changes that I just didn't contribute. If you plan to document a library API (I did it for libubox for example as I learnt), how do you make sure that people is going to find it? How can I see the whole structure of the Wiki? If I am planning to contribute to what users need more, how can I know which parts users find harder to understand? This is why I am proposing a Github based workflow. Users of the project (be them developers, final users or whatever) can raise issues in the documentation repo for help about things that are not clear enough. Contributors can send PRs reorganizing documentation without having to gain admin powers in the wiki. And most important, we can have a peer review to make sure that the content is correct, because let's be fair, OpenWRT/LEDE is not easy to understand without reading the code. People that assisted or watched the stream of the OpenWRT Summit know that most of the questions towards the board were about making contributions and usage easier. Documentation improvements for both developers and final users was the most demanded thing. I admit that documentation has improved a lot since the reboot, there are guides and howtos now, but even these guides already contain some duplicates and unstructured information. The amount of CPU (effort/concentration) one needs to structure something unstructured (a wiki) is always bigger than to structure something structured by default (a book). I think with this I have exposed some of the most relevant arguments. If anyone wants to have a proper debate, please let's continue in the arguman[1] page I have created, and expose your concerns there so that they don't get lost in a stream of text. [1] Arguman page on opernwrt/lede docs: http://en.arguman.org/openwrtlede-should-change-to-sphinxgit-based-docs-instead-of-wiki Cheers, Javier _______________________________________________ Lede-dev mailing list Lede-dev@lists.infradead.org http://lists.infradead.org/mailman/listinfo/lede-dev
