Re: [Ksummit-discuss] [TECH TOPIC] Documentation

[Shuah Khan <skhan@linuxfoundation.org>]

On 6/12/20 3:07 AM, Mike Rapoport wrote:
> On Thu, Jun 11, 2020 at 11:28:09AM -0700, Joe Perches wrote:
>> On Thu, 2020-06-11 at 12:03 -0600, Shuah Khan wrote:
>>> People that know the sub-systems well might not
>>> have time to document and more importantly keeping the documents
>>> updated.
>>
>> So you somehow expect people that do _not_ know the
>> sub-system well to produce good and useful documentation?
> 
> Writing documentation is a way to learn.
> 

+1

I find it useful and I also use it as learning tool. When I attempt
document or explain a concept or an area, I get a deeper understanding
of that area.

> Besides, to produce good and usefull documentation it is not necessary
> to have very deep understanding of all the small details. The writer
> must capture the large picture and be able to explain it.

+1.

I would counter the argument that new developers can't document an area,
they can and the document can be reviewed by experts.

A fresh set of eyes bring a new perspective and could help improve the
code, just like the benefits of having others test your code.

I have had some level of success adding documentation tasks in the
mentoring program. It does require experts spending time reviewing to
make sure it is correct.

One thing we could do is creating a list documentation todo and review
which is part of our development workflow anyway.

thanks,
-- Shuah
_______________________________________________
Ksummit-discuss mailing list
Ksummit-discuss@lists.linuxfoundation.org
https://lists.linuxfoundation.org/mailman/listinfo/ksummit-discuss