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 CF2FA7F for ; Mon, 3 Aug 2015 13:08:35 +0000 (UTC) Received: from v094114.home.net.pl (v094114.home.net.pl [79.96.170.134]) by smtp1.linuxfoundation.org (Postfix) with SMTP id 5FC7117E for ; Mon, 3 Aug 2015 13:08:34 +0000 (UTC) From: "Rafael J. Wysocki" To: Davidlohr Bueso Date: Mon, 03 Aug 2015 15:35:36 +0200 Message-ID: <1893963.CjFnBCekyb@vostro.rjw.lan> In-Reply-To: <1438499234.2249.122.camel@stgolabs.net> References: <20150801164142.653012af@lwn.net> <1438499234.2249.122.camel@stgolabs.net> MIME-Version: 1.0 Content-Transfer-Encoding: 7Bit Content-Type: text/plain; charset="utf-8" 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 Sunday, August 02, 2015 12:07:14 AM Davidlohr Bueso wrote: > On Sat, 2015-08-01 at 16:41 +0200, Jonathan Corbet wrote: > > There could, I think, be value in talking about where we would like our > > docs subsystem to go. > > Perhaps more important would be focusing on ways of _improving_ our > already existing Documentation/*. Some areas really stink, a combination > of stale and incorrect information. My brain is too melted to give exact > examples, just one of those things you run into. > > In general core kernel docs is pretty well maintained. This, I believe, > is a result of maintainers pushing for quality docs with patches. I > don't know about others, ie drivers, but perhaps examples could be taken > from -tip, or akpm. > > > What kind of changes would we like to make to render > > our docs more accessible, more current, and easier to contribute to? > > I would say that if anyone has anything meaningful to say, he or she, > will find the way. As you mentioned, nicely formatted plain text files > work well. > > 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. 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. Thanks, Rafael