Hi Joshua, Le ven. 8 mai 2026 à 13:58, Joshua Zivkovic via dev <[email protected]> a écrit : > 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/
Just a quick correction: https://apache.github.io/buildstream/ is an implementation detail (we're using github pages) and it shouldn't be used. (buildstream.build is also hosted by gitlab pages, and I won't give the url to avoid further confusion). > 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. Right, this is the only duplication we currently have. > apache.github.io/buildstream links back to buildstream.build and is > otherwise identical to buildstream.build which is distracting but really No, it is not "identical to buildstream.build". It contains the master version of docs.buildstream.build. > 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. This one should be easy to move. But the homepage also has some information that is not in the documentation. It would be nice to move that as well. > 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. Yes, it would be nice to put everything in one place, including the plugins documentation. The current documentation could be extended with the ASF links (which are really the only thing that is in buildstream.apache.org but not in the older buildstream.build), and be used as the (only) website. But to do that, we need to also change the landing page https://docs.buildstream.build/ to look more like the home page, not only refer to the documentation. > 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. Thanks for starting this discussion, I hope we can get the ball rolling. It's mainly that the website was mostly neglected rather than there being no desire to improve things. Cheers, Abderrahim
