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
