Re: How can we decrease the cognitive overhead for contributors?

[Simon Tournier]

Hi,

On Thu, 24 Aug 2023 at 02:18, Csepp <raingloom@riseup.net> wrote:

> By the way, that's another issue.  Using a TeX based document format for
> the docs is, uuuh, maybe not the best idea.  Info is a pretty okayish
> documentation reader, but it's a relatively big barrier to entry
> compared to what you need to know to make a small edit to the Arch wiki.
> This way mostly just experienced contributors write docs, not the
> users who just want to document how they made some weird use case
> possible.

Similarly as the term “contribution” is large, I would like to point
that the term “docs” is pointless here.  Are we comparing the Archi wiki
with printed-quality manual?  Somehow, there is a range of documentations
and they do not necessary require the same format.

Well, moreover, I think that the format is a fake problem.  To be
explicit, I also dislike the Texi format but the main reason why I do
not contribute much to any documentation kind is clearly not the format,
instead it is, by far far before, my first main reason is the task
appears to me boring and it barely fixes my immediate annoyances.

To be precise, I have between 5 and 10 items on my TODO list mentioning
“Improve the documentation for this” or “Write a blog post for that”.
It’s stuck not because the Texi format but because writing is hard.  For
instance, I could write to my blog using Org-mode format or to one of
the Guix blogs using Markdown format.

Now, if you speak about Fixing-Typo sort of contribution for the
documentation, I am sure that just pointing the section and the typo via
any mailing list or via IRC, and the typo will be fixed before the end
of the next hour. ;-)

Cheers,
simon