[Ksummit-discuss] [CORE TOPIC] Documentation

[Laurent Pinchart]

Hi Tim,

On Tuesday 04 August 2015 11:21:35 Tim Bird wrote:
> On 08/04/2015 07:42 AM, Konstantin Ryabitsev wrote:
> > On Tue, Aug 04, 2015 at 04:50:44PM +0300, Dan Carpenter wrote:
> >> Presumably, someone has a webpage with all the docs pre-built.
> > 
> > https://www.kernel.org/doc/htmldocs/
> 
> That's good.  When this thread started I tried looking for
> an online instance of prebuilt docs, but the latest one I found
> was for 2.6.30.
> 
> If this is maintained consistently, maybe this site should be
> (wait for it...) documented somewhere. ;-)
> 
> On a more serious note, I'd be in favor of:
> 1) switching to markdown or AsciiDoc.  Pandoc markdown
> looks pretty capable, but I wouldn't want to introduce
> a dependency on Haskell.  I think for the types of things
> we do, just about any markdown would do.  Pandoc claims
> to be able to convert between many different formats,
> including AsciiDoc, and to convert to many different outputs.
> 
> I think having plain text will lower the barrier to
> editing the docs.
> 
> 2) keeping the intro texts in the source files.  That
> way doc changes should be more visible to maintainers,
> and they're arguably more accessible when you're poking
> around the code.

It's more than intro text in my opinion. Look at 
https://www.kernel.org/doc/htmldocs/drm/index.html, it tries to be a 
guide/walk-through type of documentation. The amount of documentation is so 
large that it would be quite impractical to keep it in source files. Or we 
could have source files containing only documentation comments, but that would 
defeat the point :-)

-- 
Regards,

Laurent Pinchart