Re: Documentation: update and future improvements

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

On Fri, 2018-06-22 at 20:02 +0900, Agustín Benito Bethencourt via
Buildstream-list wrote:
> Hi,
>  
> On Friday, 22 June 2018 19:50:57 JST Laurence Urhegyi via
> Buildstream-list wrote:
> > Hi,
> >  
> > After some MRs have landed this week, we now have pretty solid
> documentation
> > for newcomers to the project. See here:
> >  
> > https://buildstream.gitlab.io/buildstream/
> >  
> > I think we now need to focus on improving the documentation for the
> more
> > advanced features of the the tool, and so I have opened the
> following ticket
> > to capture this:
> >  
> > https://gitlab.com/BuildStream/buildstream/issues/437
> >  
> > I've suggested a way to structure this, which is essentially having
> > tutorials to show the different use cases that BuildStream caters
> for,
> > which get more complex as the reader goes through them:
> >  
> > * Building a project
> > * Developing a project
> > * Working with Buildstream in a team
> > * Advanced Projects

So we do have a structure for user facing documentation by now,
finally.

Currently we have two categories of hand tailored user facing
documentation at:

   http://buildstream.gitlab.io/buildstream/main_using.html


Tutorial Entries
~~~~~~~~~~~~~~~~
I expect to add a couple of chapters to this but to keep it limited. In
the tutorial we still need to teach:

  o integration-commands
  o split-rules and compose
  o workspaces

This is a journey through the basics of BuildStream which should be
kept brief enough to complete the exercises within in a few hours.


Examples
~~~~~~~~
These have almost the same structure as the tutorial entries do, except
do not have an overview and summary section, these focus more on
explaining how a given project example works.

An abundant number of things could be exampled in these examples, the
focus here is to have examples that are proven to keep working (we test
that they work in CI).


I expect that if one day we have a very large number of examples; we
may want to structure them in categories like the ones you describe.
Until we actually have a lot of material to categorize, I'd rather just
keep it a single list of named examples.

Cheers,
    -Tristan