Wiki as documentation (and registration problems) (was: Implementing a WKS solution)

[Jeffrey Walton]

On Fri, Feb 26, 2021 at 3:37 AM Bernhard Reiter <bernhard at intevation.de> wrote:
>
> Am Montag 22 Februar 2021 16:31:14 schrieb Dashamir Hoxha via Gnupg-devel:
> > Wiki is good, but a documentation system based on git flow (with merge
> > requests, reviews, etc.) might be better.
>
> The wiki has a lower access barrier, so it is easier to make changes.
> On the other hand the information can be less reliable (because many people
> can just change it). Andre any myself keep an eye on changes a bit, so bad
> changes get reverted in a reasonable timeframe.

Information management is hard.

I find wikis are the best way to disseminate long term, less
frequently changing information. In contrast, README's don't work.
They have not worked in 50 years and they are not going to magically
start working now. Mailing lists are good for immediate problems, like
break fix. But mailing lists are harder to search and follow.
Information is too disjoint and spread across multiple posts.

Wikis have a confounding property (to me) that they always arrive at
the right answer. It does not matter that contributors are not subject
matter experts. The crowd always arrives at the right answer. Someone
wrote a paper explaining the property, but I have never been able to
locate it. Also see
https://www.npr.org/sections/money/2015/08/07/430372183/episode-644-how-much-does-this-cow-weigh.

Wikis are also well indexed by search engines so users who make an
effort to search can readily find the information. In one experiment
OpenSSL performed, the topic of "How to compile and install openssl"
was tested. The subject used to get 10 to 20 questions a month on the
OpenSSL mailing list. After adding a detailed wiki page on the
subject, the mailing list questions dropped to nearly 0.

I also find it a good habit to... When someone asks a question on the
mailing list or Stack Overflow, add a topic about it in your wiki.
When the next person asks the same question, provide a link to the
topic in your wiki. Search engines pick up on those inward links and
drive your canonical answer to the top. Then, users find your
canonical answer more easily.

Wikis also help relieve project maintainers from writing all the
documentation themselves. If a project maintainer complains they don't
have time, then they need to use the right tool for the job and learn
to delegate to the crowd.

Jeff