Feedback on documentation philosophy requested

[Brad Bishop <bradleyb@fuzziesquirrel.com>]

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