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
>