From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from smtp1.linuxfoundation.org (smtp1.linux-foundation.org [172.17.192.35]) by mail.linuxfoundation.org (Postfix) with ESMTPS id 9BE8C8AD for ; Mon, 3 Aug 2015 20:45:10 +0000 (UTC) Received: from mail-pa0-f46.google.com (mail-pa0-f46.google.com [209.85.220.46]) by smtp1.linuxfoundation.org (Postfix) with ESMTPS id F0FB9123 for ; Mon, 3 Aug 2015 20:45:09 +0000 (UTC) Received: by padck2 with SMTP id ck2so98060180pad.0 for ; Mon, 03 Aug 2015 13:45:09 -0700 (PDT) Date: Mon, 3 Aug 2015 13:45:05 -0700 From: Dmitry Torokhov To: Jonathan Corbet Message-ID: <20150803204505.GF38878@dtor-ws> References: <20150801164142.653012af@lwn.net> <1438499234.2249.122.camel@stgolabs.net> <1893963.CjFnBCekyb@vostro.rjw.lan> <20150803083311.5abd23f6@lwn.net> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <20150803083311.5abd23f6@lwn.net> Cc: ksummit-discuss@lists.linuxfoundation.org Subject: Re: [Ksummit-discuss] [CORE TOPIC] Documentation List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , On Mon, Aug 03, 2015 at 08:33:11AM -0600, Jonathan Corbet wrote: > On Mon, 03 Aug 2015 15:35:36 +0200 > "Rafael J. Wysocki" 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. My main issue with the DocBook is that it is not generated by default and it is actually takes a while to generate them; otherwise I woudl love to be able to catch at least issues breaking existing docs as early as possible. Thanks. -- Dmitry