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

Laurent Pinchart
2020-06-12T08:19:21Z

H Shuah,

On Thu, Jun 11, 2020 at 01:44:45PM -0600, Shuah Khan wrote:
> On 6/11/20 12:28 PM, 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?
>
> I didn't suggest anything like that. I merely mentioned that
> lack of bandwidth is a reason for outdated documentation.

I think it may be more of a priority issue than a bandwidth issue. Most
subsystems have traditionally not put lots of effort in documenting
designs and APIs, and very few of them, even today, enforce
documentation rules. I don't disagree that some area of the kernel have
little available bandwidth, we have some very small subsystems, or niche
areas where only a handful of people would be able to understand what's
going on (and if you ask me, that's a reason to have more documentation,
not less :-)). We also have large subsystems where policies have been
put in place over time to get developers to write documentation. I'm
thinking about V4L2 or DRM for instance, where the former has extensive
documentation of the userspace API, and the latter extensive
documentation of the in-kernel API. I believe other subsystems could
follow if maintainers considered lack of documentation to be a blocker
on patch submission.

This would however leave some developers in an uncomfortable situation.
While writing documentation is no fun for most of us, it gets much worse
for developers who are less fluent in English. Learning how to write
good documentation is hard enough without having to also learn a new
language. I think this is a problem that needs to be addressed on its
own.

Another issue that I also believe is important is where to put the bar
when it comes to documentation quality. I've reviewed many documentation
patches where I wasn't completely happy with the proposal (as I'm prone
to nit-picking during review I'll take blames here). Something that is
clear to the author of the code won't be to someone who has less
knowledge in that area, and more often that not patch authors don't
write documentation from the point of view of the reader. This is
something that can be learnt though, and I believe the kernel would
benefit from involving more technical writers who could help reviewing
documentation submissions and point out inconsistencies. There's a
matter of budget there though, it may be difficult to attract technical
writers who would help just for the fun of it.

> As for solutions, I am hoping one or two viable options will
> bubble up as we talk about the issue on this thread and at
> the kernel summit.

--
Regards,

Laurent Pinchart