Improving people's experience with technical engagement in OpenBMC

[Andrew Jeffery]

Hi all,

At OSFC I spoke to a few people who were working with OpenBMC about
what they felt were pain-points in the project. If there was one word
to summarise the responses, it would be "fragmentation". There's
concern about:

   1. The identity of the project being fragmented by its downstream
      forks
   2. The fragmented set of maintainers that people need to coordinate
      with to land complex features
   3. The fragmentation of features and capabilities over so many
      repositories
   4. The fragmentation of focus (both project developers and people
      trying to exploit OpenBMC for their platforms) driven by the
      phosphor-inventory-manager vs entity-manager split

While there are some fundamental problems there, the feelings were that
there are quality-of-life improvements we can make to the project's
documentation. It doesn't help that the documentation itself is also a
bit fragmented, but this gives us a pragmatic place to start fixing
things.

The first point can ultimately be addressed with some thoughtful words,
but while that's the case, I'm going to set it aside for the moment.
The second point is harder to address with documentation; really it
needs some consolidation to emerge from the third point, which is a bit
of a social and technical reorganisation rather than a documentation
effort. However, short of that, it can be patched over for now with
some improved documentation to make the project features discoverable.
The fourth point I think can be tackled by documenting the problem and
the consequences of the choice, along with perhaps picking a more
modern platform than romulus to feature in the documentation.

So to tackle the third and fourth points, I guess there are a few
places documentation can exist:

https://openbmc.org/

Currently this links to the Linux Foundation announcement, some 3 year
old release notes (at the time of writing), the github wiki, the
project charter, and finally to

https://github.com/openbmc

Of all of these, the latter is likely the most helpful, followed by the
wiki.

I expect most recognised thing we have documentation-wise inside the
project is the docs repo:

https://github.com/openbmc/docs

But what I expect people will hit either first or most frequently is
the metadata repo README:

https://github.com/openbmc/openbmc

Currently this behaves as the documentation entry-point, as you're
going to need this repo if you're trying to build the project. The
README talks about the TSC, CI, and a few other things that start to
get a little tangential for the repo itself. If we acknowledge the
other places documentation can exist, I think this can become a bit
more focused, and we can move some of the tangential things elsewhere.

One suggestion was that to address point 3 it would help exploit the
organisation profile README[1]. For example, u-bmc provides a project
overview in the same way:

https://github.com/u-bmc

[1]: https://docs.github.com/en/organizations/collaborating-with-groups-in-organizations/customizing-your-organizations-profile#organization-profile-readmes

The OpenBMC github organisation is already linked to from openbmc.org,
and I think the profile README is something we should exploit.

My proposal is that we do so from the perspective of people trying to
engage OpenBMC with varying motivations. Here are a few I came up with:

   1. I'm an owner of an OpenBMC-based platform and I'd like to learn
      how I can use it
   2. I administer many platforms and I'd like to integrate an OpenBMC-
      based platform into my hosting environment
   3. I'm an ODM and I'm looking to port OpenBMC to my platform
   4. I'm a BMC SoC vendor and I'd like to integrate support for my
      products into OpenBMC
   5. I already hack on OpenBMC and would like to improve my workflow

If you think there are other perspectives from which people engage with
the project that are useful to cover here, please tack them on.

Otherwise, I think the next step is to identify what documentation we
can point to for each case, and add it in.

If there's no significant opposition to doing this in the github
organisation profile README I'll look at setting it up, and populating
it along the lines of what I've outlined above.

Andrew

PS: Thanks to the following for the chats (in no particular order):
Alexander, Marvin, Sam, Oliver, Jean-Marie, Marco, Arthur, and Paul,
among others!