Hi Joshua, > My simple proposal to start things off would be to merge > https://buildstream.apache.org/installation.html into docs.buildstream.build
Yes please, I think that makes sense to have all docs in same place (a support versioning as you mentioned etc) Cheers, Javier On 8 May 2026 13:57:35 WEST, Joshua Zivkovic via dev <[email protected]> wrote: >Hi all, > >I've been looking through the BuildStream documentation recently and can't >help but notice the unusual separation as well as duplication across multiple >URLs: > >- https://buildstream.apache.org, > >- https://apache.github.io/buildstream/, > >- https://docs.buildstream.build/ > >- https://buildstream.build/ > >As I understand it, there is work to deprecate buildstream.build and move >everything under buildstream.apache.org so any duplication there is to be >expected but the rest is hard to keep up with. > >apache.github.io/buildstream links back to buildstream.build and is otherwise >identical to buildstream.build which is distracting but really I'm more >interested in the separation of docs.buildstream.build and buildstream.build. >docs.buildstream.build contains basically all BuildStream documentation except >for installation instructions (excluding installing from source for some >reason), which can instead be found at https://buildstream.build/install.html. >I suppose that should be https://buildstream.apache.org/installation.html now. > >Aside from the various homes for bits of documentation, there is the obvious >difference in the page style of the installation documentation and the >"general" documentation; which makes the hop from one to the other quite >jarring and more unusual. There should be one style decided on and used >consistently. > >I think it is fair to reason that the docs should be unified in some sense. >This will of course require some discussion which is why I'm raising this >here. I believe the intended home is indeed buildstream.apache.org so bringing >~everything~ together under there would be the ideal goal. > >My simple proposal to start things off would be to merge >https://buildstream.apache.org/installation.html into docs.buildstream.build >and have the result be hosted at buildstream.apache.org. This preserves >different versions of the documentation, that apache.github.io/buildstream >appears to be missing, and of course brings the installation documentation in >to the same place as the rest of the documentation too so is already an >improvement. As a step further, it would possibly be a good idea to also >include plugin documentation instead of that being entirely separate too but >that's a different problem to discuss. > >I'm hoping this can be a fruitful discussion to improve the discovery and >navigation of the existing documentation so users as well as developers have >an easier time working with BuildStream. > >Kind regards, > >Josh Zivkovic > > >
