Some Improvemens to docs/website

[Javier Jardón <ja...@codethink.co.uk>]

Hi BuildStreamers!

We think current first impressions when dealing with buildstream are not
optimal, and we think part of the problem is that the website and especially the
installation instructions could be a bit more clear

We would like to help to make the current situation better

Problems we have identified:
- Installation instructions from https://buildstream.build are fragmented and
confusing, partly because they're an attempt to use the same set of instructions
for both buildstream1 and buildstream2.
- Contents in the webpage tend to get out of sync

Propossed solution:
- We think installation instructions should be part of the documentation,
maintained from inside the buildstream repository. That way, they can be kept up
to date and accurate for the specific branch or tag that they are associated
with.
- Move installation instructions at https://buildstream.build back to the
documentation at https://docs.buildstream.build  [1], MR [2]
- Buildstream 1 already has installation instructions in the docs (
https://docs.buildstream.build/1.4.3/main_install.html). 
- Improve docs there as needed
- In parallel with this we would like to make some improvements to the website
to make it simpler and hence more maintenable (and if possible a bit more
attractive) [3]

Of course all this will be done through normal review process using MR's (like
[2]), so any can review the changes

What do you think? Does anyone have any reservations against above plan?

Cheers

[1] https://gitlab.com/BuildStream/buildstream/-/issues/1364 - Reintroduce
install instructions to buildstream docs
[2] https://gitlab.com/BuildStream/buildstream/-/merge_requests/1999 -
Reintroduce install instructions (MR)
[3] https://gitlab.com/BuildStream/website/-/issues/31 - Slim down the website

Re: Some Improvemens to docs/website

[Tristan Van Berkom <tr...@codethink.co.uk>]

Hi Javier,

Looks like we've already got some of this done, looking good !

On Fri, 2020-07-24 at 12:43 +0100, Javier Jardón wrote:
> Hi BuildStreamers!
[...]
> Propossed solution:
> - We think installation instructions should be part of the documentation,
> maintained from inside the buildstream repository. That way, they can be kept up
> to date and accurate for the specific branch or tag that they are associated
> with.
> - Move installation instructions at https://buildstream.build back to the
> documentation at https://docs.buildstream.build  [1], MR [2]
> - Buildstream 1 already has installation instructions in the docs (
> https://docs.buildstream.build/1.4.3/main_install.html). 
> - Improve docs there as needed
> - In parallel with this we would like to make some improvements to the website
> to make it simpler and hence more maintenable (and if possible a bit more
> attractive) [3]

Agree and disagree.

There are two classes of installation related documentation:

* User facing
* Developer/Packager facing

I think that developer/packager facing installation documentation, i.e.
anything which needs to document dependencies and build/install
procedures, is certainly BuildStream version specific and needs to be
packaged along with the BuildStream release tarballs (and consequently
published under version specific documentation pages at
docs.buildstream.build as a side effect).

This does not mean we don't need to still have a user facing
documentation store for installing BuildStream, which I think should
remain on the website and not be version specific.

In more detail:

* User facing documentation should be very simple to follow, at most we
  should have material along the lines of:

  - What single command you can run on your linux distro of choice to
    install BuildStream.

    As we release BuildStream 2, we should keep an eye on which version
    of which distro has BuildStream 2 instead of BuildStream 1, and we
    will need to link to some more complex information about supporting
    a parallel installation with a virtual environment.

    This parallel installation docs story is a BuildStream 2 blocker
    which Chandan started on, it will have to be decided where this
    has to live, but we'll need to link to it for users who are in
    a bind and don't have the right version they need from their
    distro.

  - A link to the latest version of the native win32 bundled one-click
    installer (if and when this exists)
  - A link to the latest version of the osx native bundled one-click
    installer (if and when this exists)

* The developer/distro packager facing documentation should not make
  too much of an effort to be too user friendly and hand holding.

  This documentation is rich in terse detail, and I think it loses
  some measure of value when being cluttered with too much user-facing
  hand holding (of course it should be made easy to read and follow,
  but let's not pretend that this is a one-click install story or
  that nothing can go wrong).


In general, I feel that we do need to slim down the website a lot to
something more manageable, but I feel that the approach taken in:

   https://gitlab.com/BuildStream/website/-/merge_requests/143

is far to drastic.

We don't need to slim it down to a single page, we need to have a one-
stop easy install guide that is user facing, we should also have a news
page for announcing releases and announcing any hackfests or posting
any BuildStream related news (ideally we should have this with a little
RSS feed widget which is easy enough to implement).

I think we can do away with the FAQ and a lot of the remaining fluff we
have on the website which we just don't have manpower to maintain.

Cheers,
    -Tristan

Re: Some Improvemens to docs/website

[Douglas Winship <do...@codethink.co.uk>]

Hi all

To update, we now have an MR to update the buildstream website.

https://gitlab.com/BuildStream/website/-/merge_requests/143

This MR takes the existing website and condenses it to a single page.
It removes a lot of duplicated information and deletes the 'News'
section. (The News section hasn't been updated in 16 months, and
currently makes the project look like it's been abandoned.)

Comments and discussion would be much appreciated.


Douglas

On 24/07/2020 12:43, Javier Jardón wrote:
> Hi BuildStreamers!
>
> We think current first impressions when dealing with buildstream are not
> optimal, and we think part of the problem is that the website and especially the
> installation instructions could be a bit more clear
>
> We would like to help to make the current situation better
>
> Problems we have identified:
> - Installation instructions from https://buildstream.build are fragmented and
> confusing, partly because they're an attempt to use the same set of instructions
> for both buildstream1 and buildstream2.
> - Contents in the webpage tend to get out of sync
>
> Propossed solution:
> - We think installation instructions should be part of the documentation,
> maintained from inside the buildstream repository. That way, they can be kept up
> to date and accurate for the specific branch or tag that they are associated
> with.
> - Move installation instructions at https://buildstream.build back to the
> documentation at https://docs.buildstream.build  [1], MR [2]
> - Buildstream 1 already has installation instructions in the docs (
> https://docs.buildstream.build/1.4.3/main_install.html).
> - Improve docs there as needed
> - In parallel with this we would like to make some improvements to the website
> to make it simpler and hence more maintenable (and if possible a bit more
> attractive) [3]
>
> Of course all this will be done through normal review process using MR's (like
> [2]), so any can review the changes
>
> What do you think? Does anyone have any reservations against above plan?
>
> Cheers
>
> [1] https://gitlab.com/BuildStream/buildstream/-/issues/1364 - Reintroduce
> install instructions to buildstream docs
> [2] https://gitlab.com/BuildStream/buildstream/-/merge_requests/1999 -
> Reintroduce install instructions (MR)
> [3] https://gitlab.com/BuildStream/website/-/issues/31 - Slim down the website
>
>