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

[Daniel Vetter <daniel.vetter@ffwll.ch>]

On Tue, Aug 4, 2015 at 4:28 PM, Laurent Pinchart
<laurent.pinchart@ideasonboard.com> wrote:
>> > A good (or bad example, depending on how you see it) of this is the
>> > DRM/KMS documentation available from Documentation/DocBook/drm.tmpl. I
>> > spent a considerable amount of time writing it, it got reviewed, merged in
>> > the kernel, and has now been rendered completely useless as the DRM/KMS
>> > internal API has evolved and the documentation hasn't been updated
>> > despite my repeated requests. That was extremely demotivating, and made
>> > me give up documenting DRM/KMS at all.
>>
>> drm having gone downhill is why I want to pull it out of the template
>> into code. E.g. we have extensive docs for vtables, but since they're
>> not next to the vtables in the code no one updates those. And
>> duplicating a summary in kerneldoc and then the extended version in
>> the docbook is even worse imo.
>
> The problem is two-fold. Extensive vtables documentation is definitely good,
> but it mostly serves as API reference documentation. I believe we also need a
> guide type of documentation that goes through the bits and pieces drivers need
> in a logical order. That should of course be linked to the vtables reference
> documentation, but it should be a natural text flow type of documentation that
> driver developers can read from start to end, guiding them in the process of
> writing a DRM/KMS driver.

Oh the vtables is just the blocker why I didn't start this yet - I
really don't like the current duplication we have. Fully agreed that
we need overview docs to tie it all together and explain how it works.
With markdown we can even do inline code snippets, which should help a
lot with explaining how to use certain helper libraries.
-Daniel
-- 
Daniel Vetter
Software Engineer, Intel Corporation
+41 (0) 79 365 57 48 - http://blog.ffwll.ch