Feedback on documentation philosophy requested
Brad Bishop
bradleyb at fuzziesquirrel.com
Thu Sep 19 06:41:14 AEST 2019
Hello OpenBMCers
Over here at IBM we are just getting started on a large-ish project. The
effect of which I’d like to focus on with this thread is that we will be
generating a fair amount of documentation.
I’m not talking about documentation for existing function. There is
certainly a need for that too but that is also something to tackle in
another thread. Rather, I’m talking about new designs and documentation
for new features.
Some of the new features we’ll be documenting will -not- be interesting to
some/many/most/all in the OpenBMC community. For the features that fall
more towards the most/all end of that spectrum, I ask for your thoughts on
a couple points:
- Should these docs and designs be segregated somehow? Would they become a
burden on the rest of the community if not?
- I’d like to contribute a process around documentation that helps
contributors figure out where and how to document things like this. A
really rough thought I have here is some kind of flow chart or decision
tree that could be applied to a document or set of documents, the output of
which would be how to break up your documentation into pieces and/or where
to put it/them. Does anyone have any ideas here?
As you ponder these questions a couple things to keep in your head:
- At the moment all designs are unconditionally found in
openbmc/docs/designs.
- We have documentation in openbmc/docs, *-dbus-interfaces, and various
sub-project repo READMEs. Any others?
- My observation is that the project is headed away from micro services and
towards larger applications - highly configurable at build time. bmcweb
and phosphor-logging are great examples of this. Think Linux/KBuild (but
without modules). What this means is that code with relatively few users
(or even just one) goes in the same codebase as the code with many users.
This seems counter to segregating documentation and designs of the code
with few users.
- An example of an un-interesting feature might be the support we’ll add
for the hardware management console. The HMC is a management appliance we
sell and it has a custom REST API [1], which we’ll implement in bmcweb
(tucked behind cmake flags that compile the support out of course, as
described in the previous bullet).
A couple simple ideas that have been thrown around…
- put vendor subfolders in openbmc/docs/designs
- document vendor specific features in meta-<vendor>/docs
If you are still reading, thanks! I look forward to hearing your ideas.
-brad
[1]
https://www.ibm.com/support/knowledgecenter/TI0003N/p8hat/p8hat_partitioningwithanhmc.htm
More information about the openbmc
mailing list