Improving the docs/ repo

Improving the docs/ repo

[Gunnar Mills]

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.

Improve the glossary

Some automation, check for dead links, markdown formatted is available 
for the reviewer.

Improve the layout of the docs/ repo.

Improve the README, have a well laid out starting point.

Re: Improving the docs/ repo

[krtaylor]

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.

Love this - I'll help as I can. I'd like to see TSC and maintainer 
agreement of more strict guidelines.

> Improve the glossary

We can add the BMC terms that I started, now where did I put that...

Kurt Taylor (krtaylor)

> 
> Some automation, check for dead links, markdown formatted is available 
> for the reviewer.
> 
> Improve the layout of the docs/ repo.
> 
> Improve the README, have a well laid out starting point.

Re: Improving the docs/ repo

[Adriana Kobylak]

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.

Re: Improving the docs/ repo

[Vijay Khemka]

On 10/23/19, 8:23 AM, "openbmc on behalf of Adriana Kobylak" <openbmc-bounces+vijaykhemka=fb.com@lists.ozlabs.org on behalf of anoo@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.
    

Re: Improving the docs/ repo

[krtaylor]

On 10/23/19 10:22 AM, Adriana Kobylak 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.

This is absolutely the way it *should* be. Commits and/or wip. For the 
IRC averse and design documents, it lets the community know what you are 
planning and gives them the ability to be involved early on.

Kurt Taylor (krtaylor)