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

[Tim Bird <tim.bird@sonymobile.com>]

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.
 -- Tim