Improving the docs/ repo

[Vijay Khemka]

On 10/23/19, 8:23 AM, "openbmc on behalf of Adriana Kobylak" <openbmc-bounces+vijaykhemka=fb.com at lists.ozlabs.org on behalf of anoo at linux.ibm.com> wrote:

    On 2019-10-23 08:51, krtaylor wrote:
    > On 10/22/19 11:38 AM, Gunnar Mills wrote:
    >> Looking to improve the docs/ repository.
    >> Is anyone interested in getting involved in improving the document 
    >> repository? Looking for either ideas or contributions.
    >> 
    >> Some ideas:
    >> Better document the process for submitting documents which should 
    >> improve the quality of documentation being submitted.
    >> 
    >> Design template improvement, spell out any additional expectations 
    >> that come in review. E.g. All fields must be filled out, involve the 
    >> community before submitting a template, avoid internal acronyms, 
    >> expand on when the template is needed.
    
    How do people feel about having smaller commits for the docs, like we 
    encourage for source code? Would it make it easier to review? An example 
    for designs would be one commit with the problem statement, next commit 
    adds the requirements, next adds one solution proposal, etc.

I agree with Adriana. We can also have some directory structure based on feature
or group of features. And under the directory, either everything, can be like, design,
requirement, functionality details in same file or can have multiple files. But certainly
we need to rearrange it. And I am up for it.