[LEDE-DEV] Lede/Openwrt documentation

[Javier Domingo Cansino]

> 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