[LEDE-DEV] Lede/Openwrt documentation

Sun Nov 12 12:03:37 PST 2017

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 <javierdo1 at gmail.com> 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, 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 at lists.infradead.org
> http://lists.infradead.org/mailman/listinfo/lede-dev