Re: Feedback on documentation philosophy requested

[Brad Bishop <bradleyb@fuzziesquirrel.com>]

Bumping this thread in case anyone had intended to reply but forgot.

thx! - brad

> 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