Re: Documentation: update and future improvements

[Laurence Urhegyi <Laurence Urhegyi codethink co uk>]

On 22/06/18 18:30, Tristan Van Berkom via Buildstream-list wrote:
> > > 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

<snip>
> Tutorial Entries
> ~~~~~~~~~~~~~~~~
> I expect to add a couple of chapters to this but to keep it limited.

Were you planning to do the work and land these before GUADEC? I've been 
discussing with Phil Dawson and he's said he'd like to pick this up, which makes 
sense as he's still learning BuildStream.

 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.

You seem to be vaguely endorsing the suggested structure here? We should ensure 
the tutorials cover the above and we keep them clear and brief.

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

Yes, whilst my initial mail just focused on tutorials, examples is another hot 
topic - we are planning to improve the X86-image [0] and Netsurf [1] examples.

If anyone has any further ideas for examples, we'd all welcome those too, either 
just an idea or (preferably) a patch :)

[0] https://gitlab.com/BuildStream/buildstream/issues/438
[1] https://gitlab.com/BuildStream/buildstream/issues/439

Thanks,
Laurence