Re: The documentation story

[Alberto Fanjul Alonso <albfan gnome org>]

Hi all, honored to be mention here.

I will stick to that plan to improve documentation.

- About step 2: Did you consider to add a plugin for GNOME Builder? This is an example of what it takes https://gitlab.gnome.org/GNOME/gnome-builder/blob/master/src/plugins/phpize/phpize_plugin.py. Just see our flatpak-autotools example running into Builder can be awesome.

- About step 3: I plan to work on use flatpak extensions with buildstream, (which should be straightforward) Hoping to reach people looking for "How do I..." I keep an eye on twitter and IRC, but get our official twitter account could be a game changer here.

As part of the GNOME newcomers initiative, we want to refer people to docs so they can find its way to use BuildStream, having easy access to all stacks building GNOME software, reducing the learning curve to contribute.

El mié., 16 may. 2018 a las 12:09, Paul Sherwood (<paul sherwood codethink co uk>) escribió:

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


_______________________________________________
Buildstream-list mailing list
Buildstream-list gnome org
https://mail.gnome.org/mailman/listinfo/buildstream-list