Re: [TECH TOPIC] Kernel documentation - update and future directions

[Jonathan Corbet <corbet@lwn.net>]

Laurent Pinchart <laurent.pinchart@ideasonboard.com> writes:

>> > Last year we tried an experiment with a bit of funding from the LF to
>> > create a bit of paid documentation; for a number of reasons, that
>> > experiment did not work out.  But it seems there should be a way to make
>> > some forward progress on this front.
>
> Is there anything we can learn from that failure and that number of
> reasons to make the next attempt more successful ?

I think that the experiment didn't work for a couple of reasons:

- The topic area that we settled upon was a relatively advanced one, we
  really should have started with something simpler.

- The writer who was assigned was not really up to the task; I found
  myself repeatedly having to explain basic aspects of the C programming
  language, for example.  That made it almost impossible to get a
  satisfactory document out of the process, made worse by the first
  reason listed above.
  
What it comes down to, perhaps, is the same old problem: the people who
understand the problem domain well enough to document it can generally
make a more comfortable living creating more undocumented code instead.

jon