Feedback on documentation philosophy requested

Feedback on documentation philosophy requested

[Brad Bishop]

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

Re: Feedback on documentation philosophy requested

[Brad Bishop]

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

Re: Feedback on documentation philosophy requested

[Gunnar Mills]

On 10/7/2019 3:15 PM, Brad Bishop wrote:
>
>>
>> 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?

If these documents do end up in the docs/ repo, they still need to be 
written in a way that can be consumable by the community.
Examples
  Avoid internal names/acronyms when something widely known exists
  Try to engage the community, maybe parts of the feature could be more 
common
  Any names/acronyms need to be explained if not widely used and not 
possible to avoid
  Look to upstream, e.g. instead of a new OpenBMC only interface, engage 
the DMTF and look to get that feature added to Redfish


>>
>>
>> - 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
>>
I would like to hear what others in the community think. :)

  If nothing more though on this topic going to take this as it is okay 
to allow features, like the HMC, that are probably not interesting to 
most the OpenBMC community into docs/
  https://gerrit.openbmc-project.xyz/c/openbmc/docs/+/23419 would be an 
example.

- Gunnar

>>
>> -brad
>>
>> [1] 
>> https://www.ibm.com/support/knowledgecenter/TI0003N/p8hat/p8hat_partitioningwithanhmc.htm
>