From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from smtp2.linuxfoundation.org (smtp2.linux-foundation.org [172.17.192.36]) by mail.linuxfoundation.org (Postfix) with ESMTPS id EAE3DBCC for ; Mon, 13 Jul 2015 16:37:54 +0000 (UTC) Received: from smtprelay.hostedemail.com (smtprelay0081.hostedemail.com [216.40.44.81]) by smtp2.linuxfoundation.org (Postfix) with ESMTP id 8C6B21DCA4 for ; Mon, 13 Jul 2015 16:37:54 +0000 (UTC) Received: from smtprelay.hostedemail.com (10.5.19.251.rfc1918.com [10.5.19.251]) by smtpgrave07.hostedemail.com (Postfix) with ESMTP id 8D28111A212 for ; Mon, 13 Jul 2015 16:37:53 +0000 (UTC) Date: Mon, 13 Jul 2015 12:37:50 -0400 From: Steven Rostedt To: Alexey Dobriyan Message-ID: <20150713123750.52d8a14d@gandalf.local.home> In-Reply-To: References: <201507130038.01474.PeterHuewe@gmx.de> MIME-Version: 1.0 Content-Type: text/plain; charset=US-ASCII Content-Transfer-Encoding: 7bit Cc: ksummit-discuss@lists.linuxfoundation.org, Dan Carpenter Subject: Re: [Ksummit-discuss] [CORE-TOPIC] Documentation List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , On Mon, 13 Jul 2015 12:47:23 +0300 Alexey Dobriyan wrote: > Newbies should not write documentation because they, by definition, > have little knowledge of the code. It will lead to many, many useless > and redundant comments like below whose only purpose is stealing > vertical whitespace: I agree that newbies shouldn't write documentation. But maybe what they can do is to question what a function does. And perhaps poke the maintainer (or author of said function) to write something that explains that function (only for non-static functions). Now, I say "newbies" but I would really mean experienced developers that are new to a subsystem. We don't need silly questions. Something more on the line of one experienced kernel developer reading some code of the kernel they have no idea about, and if they can't figure out what a function does, ask the question to the author. Perhaps we can get better documentation of internal interfaces out of it. There's been times where I look at other subsystems and wonder WTF a function is suppose to do. Perhaps I need to start poking the author of that code to explain it. -- Steve