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
