The documentation story

[Tristan Van Berkom <tristan vanberkom codethink co uk>]

TL;DR:

 NEWS: We now have our first user facing example !

 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.

 PLAN: Find the outline of the plan for user facing documentation.


Hi,

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 !"

This second part is an extreme case (and one which I find particularly
insulting I might add), but you get the picture: People seem to be
under the illusion that creating user facing documentation is an
effortless process, and as such they are not actually sitting down and
taking the time to actually create them - this is becoming a pattern
and it has to end.

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

In closing, I would like to highlight that this careless attitude has
not been coming from all sides, and I would like to commend in
particular James Ennis for baring with me in "holding the line" for
passable user documentation. We have however been expecting too much of
him while not affording him with the actual time needed to doing the
work.


The documentation plan / vision
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
James Ennis and I have come up with a plan a few weeks ago, which
defines an overall "plan" for comprehensive and consistent user facing
documentation.
 
This cannot of course all be executed at once, some parts of this plan
have fell into place and others are in the works.

In the hope that people can understand where we're going with this,
I'll try to formally outline the plan here.


  Step 1 - ToC
  ~~~~~~~~~~~~
  The table of contents was in need of a refactor and rethinking, this
  is not *completely* done but mostly - I am not satisfied that the ToC
  on the main page has "depth", it should be one level on the first
  page such as to give the user the choice of reading several
  interlinked "books", they are all fairly separate documentation
  and there is too much noise here for a newcomer to see on the
  face page.

  Why is the ToC important ?

  This is essential because, this forms where people are going to
  naturally submit chapters and additions to. If this is not well
  thought out, then we will end up with redundancies.

  Redundancies in the documentation do not cause crashes in software,
  but they are exactly as much as a burden as redundancies in software
  in terms of long term maintenance.
  
  So please remember, the end game here is to have a package which
  can reasonably be maintained in one person's spare time when all the
  development dries up and the dust settles, and it's my responsibility
  to make sure that we dont have redundancies. Redundancies cause
  maintenance and contribution effort to increase as "more stuff" needs
  updates with every churn, while they also cause coherency of the
  whole to decrease, as the same thing gets explained in different
  ways throughout the manual.


  Step 2 - Getting Started Walkthrough
  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  For a getting started section, we want an experience which the user
  can follow steps, read the text and perform a few exercises to learn
  what is "strictly the basics" of BuildStream.

  During this walkthrough, we should not stray into details of specific
  use cases, we should focus on one simple use case and expand on it,
  such that the user becomes well informed enough that they can at
  least start to write their own projects.

  Some of the things which the user needs to learn:

    o How to use the basic "bst build" commands
    o What is the meaning of "strict mode"
    o How to debug things in a shell
    o Start writing a project using the "manual" element, this shows
      how build elements actually work, by executing a series of
      commands
    o Use another derived element, like an "autotools" element, this
      shows the user how "variables" work, by observing the "autotools"
      reference documentation one can see how the variables are
      composed to perform the activities you would otherwise do
      manually using the "manual" element
    o We must link out to the reference manual everywhere that it is
      relevant to do so, i.e. for every feature we introduce
    o The user must be proficient at navigating the reference manual
      after completing the basic exercises

  It is very important that these "getting started" exercises remain
  limited and not particular to edge use cases, we want something very
  general here. Why ? Because we need to minimize overlap between what
  we explain in "Getting Started", and in the individual "Examples"

  Step 3 - Examples
  ~~~~~~~~~~~~~~~~~
  Examples are "How do I" format documentation.

    o How do I build on a flatpak runtime ?
    o How do I override how an element is built in subproject ?
    o Etc

  We expect there to be an unlimited amount of these possible, and as
  such it would be a complete disaster if had no real precedent and
  style to writing the examples.

  Imagine that you are reading a book and all the chapters are
  formatted differently, some have pictures at the end, others at
  the beginning, some start with a summary, you would wonder what
  the publisher had been smoking to accept this nonsense.

  So, James and I set out to "Design what is an example", what we
  came up with is not perfect and without precedent, there is not
  much of a style guide to come up with, we will have to make sure
  that we improve consistency of style and formatting while examples
  get added.

  We did at least come up with these guidelines, which are I think
  a bare minimum barrier to entry for an example:

    o An example has a "name"
    o The example in the documentation is doc/source/examples_${name}.rst
    o There is a sample project for each example, this lives in the
      directory doc/examples/${name}/
    o There is an integration test which runs in CI for the example,
      this is called tests/examples/${name}.py
    o When the example explains the ".bst" files, they do so by using
      a "literalinclude" rst directive such that we use the actual bst
      files in the sample project to render in the documentation
    o Whenever talking about any feature in BuildStream, we link to
      that feature's documentation in the reference manual.

  I think this is not a very high barrier, and I would like to thank
  Alberto Fanjul for listening to what I had to say regarding guidance
  as to how to create the example he contributed, and actually
  sitting down and following through with it, and giving me something
  to work with.

This concludes the documentation story of the day.

Thankyou for your time.

Cheers,
    -Tristan