From mboxrd@z Thu Jan  1 00:00:00 1970
Return-Path: <corbet@lwn.net>
Received: from smtp1.linuxfoundation.org (smtp1.linux-foundation.org
	[172.17.192.35])
	by mail.linuxfoundation.org (Postfix) with ESMTPS id 8A37626C
	for <ksummit-discuss@lists.linuxfoundation.org>;
	Mon,  3 Aug 2015 14:33:18 +0000 (UTC)
Received: from vena.lwn.net (tex.lwn.net [70.33.254.29])
	by smtp1.linuxfoundation.org (Postfix) with ESMTPS id 7782F19D
	for <ksummit-discuss@lists.linuxfoundation.org>;
	Mon,  3 Aug 2015 14:33:14 +0000 (UTC)
Date: Mon, 3 Aug 2015 08:33:11 -0600
From: Jonathan Corbet <corbet@lwn.net>
To: "Rafael J. Wysocki" <rjw@rjwysocki.net>
Message-ID: <20150803083311.5abd23f6@lwn.net>
In-Reply-To: <1893963.CjFnBCekyb@vostro.rjw.lan>
References: <20150801164142.653012af@lwn.net>
	<1438499234.2249.122.camel@stgolabs.net>
	<1893963.CjFnBCekyb@vostro.rjw.lan>
MIME-Version: 1.0
Content-Type: text/plain; charset=US-ASCII
Content-Transfer-Encoding: 8bit
Cc: ksummit-discuss@lists.linuxfoundation.org
Subject: Re: [Ksummit-discuss] [CORE TOPIC] Documentation
List-Id: <ksummit-discuss.lists.linuxfoundation.org>
List-Unsubscribe: <https://lists.linuxfoundation.org/mailman/options/ksummit-discuss>,
	<mailto:ksummit-discuss-request@lists.linuxfoundation.org?subject=unsubscribe>
List-Archive: <http://lists.linuxfoundation.org/pipermail/ksummit-discuss/>
List-Post: <mailto:ksummit-discuss@lists.linuxfoundation.org>
List-Help: <mailto:ksummit-discuss-request@lists.linuxfoundation.org?subject=help>
List-Subscribe: <https://lists.linuxfoundation.org/mailman/listinfo/ksummit-discuss>,
	<mailto:ksummit-discuss-request@lists.linuxfoundation.org?subject=subscribe>

On Mon, 03 Aug 2015 15:35:36 +0200
"Rafael J. Wysocki" <rjw@rjwysocki.net> wrote:

> > While I don't discourage it, I am not a fan of automated documentation.
> > As you and mtk would know, writing high quality, informative, systems
> > software documentation is an involved process. And it should be, imo.
> > Same goes for describing APIs and algorithms in code comments. Sure,
> > automation has its pros, particularly keeping docs up to date; yet this
> > does not outweigh a well crafted document, which involves actual though.  
> 
> "thought" I guess?
> 
> I have to say I agree here.

Surely nobody thinks I was saying that the documentation-writing process
can be automated! :)  But we go to some lengths now to document our APIs
in the code; I don't think we would want to break that.

> Not to mention the fact that if you are browsing the kernel tree via a web
> frontend or LXR, for example, plain text docs are really good to have.

The nice thing about formats like Markdown or ReST is that they *are*
plain text for all practical purposes.  Much better than DocBook in that
regard.

jon