* Improving the docs/ repo
@ 2019-10-22 16:38 Gunnar Mills
2019-10-23 13:51 ` krtaylor
0 siblings, 1 reply; 5+ messages in thread
From: Gunnar Mills @ 2019-10-22 16:38 UTC (permalink / raw)
To: openbmc
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.
^ permalink raw reply [flat|nested] 5+ messages in thread
* Re: Improving the docs/ repo
2019-10-22 16:38 Improving the docs/ repo Gunnar Mills
@ 2019-10-23 13:51 ` krtaylor
2019-10-23 15:22 ` Adriana Kobylak
0 siblings, 1 reply; 5+ messages in thread
From: krtaylor @ 2019-10-23 13:51 UTC (permalink / raw)
To: Gunnar Mills, openbmc
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.
^ permalink raw reply [flat|nested] 5+ messages in thread
* Re: Improving the docs/ repo
2019-10-23 13:51 ` krtaylor
@ 2019-10-23 15:22 ` Adriana Kobylak
2019-10-23 16:39 ` Vijay Khemka
2019-10-24 12:12 ` krtaylor
0 siblings, 2 replies; 5+ messages in thread
From: Adriana Kobylak @ 2019-10-23 15:22 UTC (permalink / raw)
To: krtaylor; +Cc: Gunnar Mills, openbmc, openbmc
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.
^ permalink raw reply [flat|nested] 5+ messages in thread
* Re: Improving the docs/ repo
2019-10-23 15:22 ` Adriana Kobylak
@ 2019-10-23 16:39 ` Vijay Khemka
2019-10-24 12:12 ` krtaylor
1 sibling, 0 replies; 5+ messages in thread
From: Vijay Khemka @ 2019-10-23 16:39 UTC (permalink / raw)
To: Adriana Kobylak, krtaylor; +Cc: openbmc, openbmc, Gunnar Mills
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.
^ permalink raw reply [flat|nested] 5+ messages in thread
* Re: Improving the docs/ repo
2019-10-23 15:22 ` Adriana Kobylak
2019-10-23 16:39 ` Vijay Khemka
@ 2019-10-24 12:12 ` krtaylor
1 sibling, 0 replies; 5+ messages in thread
From: krtaylor @ 2019-10-24 12:12 UTC (permalink / raw)
To: Adriana Kobylak; +Cc: Gunnar Mills, openbmc, openbmc
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)
^ permalink raw reply [flat|nested] 5+ messages in thread
end of thread, other threads:[~2019-10-24 12:13 UTC | newest]
Thread overview: 5+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2019-10-22 16:38 Improving the docs/ repo Gunnar Mills
2019-10-23 13:51 ` krtaylor
2019-10-23 15:22 ` Adriana Kobylak
2019-10-23 16:39 ` Vijay Khemka
2019-10-24 12:12 ` krtaylor
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.