Re: The documentation story

[Paul Sherwood <paul sherwood codethink co uk>]

On 2018-05-16 10:34, Tristan Van Berkom wrote:
> TL;DR:
>
>  NEWS: We now have our first user facing example !

w00t!

>  RANT: People are whining about lack of documentation, but they
>        are not backing it up with actual work - and worse, I am getting
>        garbage patch submissions, which means people think
>        documentation is not valuable.

I'm one of the whiners, and I expect to continue to whine. I didn't 
choose devcurmudgeon as a moniker by accident. In other contexts (where 
I wear the benevolent dictator cape) I can rant, but here I have to 
settle for whining :-)

>  PLAN: Find the outline of the plan for user facing documentation.
>
> First the news, thanks to Alberto Fanjul, who is a volunteer
> contributor who took my guidelines for contributing an example
> seriously, we have finally landed our first example which should set
> the precedent for any further examples to come. I did fill it out a bit
> with some explanation and links, but I am very thankful that Alberto
> gave me something to work with.
>
> It can be found in all of it's splendor and glory here:
>
>     http://buildstream.gitlab.io/buildstream/examples.html
>
>
> A highly necessary rant
> ~~~~~~~~~~~~~~~~~~~~~~~
> This is in response to the incessant whining about the lack of user
> documentation, coupled with the very clear lack of effort and value
> attribution to the docs.
>
>     On the one hand, I am hearing: "We want docs, we want then now !"
>
>     On the other hand, I am seeing: "This output copy pasted from my
>     terminal should be committed to the documentation, because it's
>     better than nothing !"

I still think that would have been true. Copy-paste of terminal commands 
IMO is a reasonable way of documenting what the actual steps are to 
achieve something. In some contexts it's **the best** way (e.g. when a 
driveby user wants to try something as fast as possible and see a 
result, before deciding to spend time learning about a thing and its 
special vocabulary).

But you're the BD here, so fine :-)

<snip>
> So, let's make this clear: Documentation is not garbage.
>
>    "Perfect is the enemy of Good"
>
> While this is true, I should add to it:
>
>    "... but garbage is just not acceptable."

I've ended up with a different framing, but similar result...

"Perfect is one of the enemies of the Good. Garbage is another"

> I have fairly high expectations of quality when it comes to merging
> code to the repository, nobody complains about this. I don't see why we
> should treat user facing documentation as in any way "less important",
> or "less of a maintenance burden" than the code itself - this is all
> part of a comprehensive whole.

+1

<snip>

I'm skipping the plan part of your email because it's too detailed for 
me to think about deeply and I'm sure its broadly sensible.

However I would like to draw your attention to a few things:

- first impressions really matter, so where a new user lands on 
buildstream the documentation needs to be as useful as possible (and 
that means short, obvious, correct etc).

- it seems obvious that we can only get first impressions once - after 
someone gets up the learning curve, their impressions are different.

- people who have been working on a project for a while are bound to 
have implicit knowledge, which leads them to perceive the documentation 
differently from real driveby/new users. and to ignore friction points 
that they've learned to breeze past

- in some cases, people developing on a project do not really understand 
how the project is used or perceived at all. i'd strongly recommend that 
developers need to be actually using bst too (and think about ironing 
out the issues as they go) otherwise we risk ending up with too much 
functionality and too little useability.

br
Paul