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 <javier...@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@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
