From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1751932AbcF2QYc (ORCPT ); Wed, 29 Jun 2016 12:24:32 -0400 Received: from tex.lwn.net ([70.33.254.29]:43259 "EHLO vena.lwn.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1751854AbcF2QY2 (ORCPT ); Wed, 29 Jun 2016 12:24:28 -0400 Date: Wed, 29 Jun 2016 10:24:26 -0600 From: Jonathan Corbet To: Markus Heiser Cc: Mauro Carvalho Chehab , Dave Airlie , Jani Nikula , Grant Likely , Keith Packard , LKML Mailing List , "linux-doc@vger.kernel.org" , Hans Verkuil , Randy Dunlap Subject: Re: [GIT PULL] doc: sphinx-4.8 DocBook to reST movement on Jon's docs-next Message-ID: <20160629102426.08570878@lwn.net> In-Reply-To: <6A1AB08B-E585-42E2-A604-D5144A7BC6B4@darmarit.de> References: <6A1AB08B-E585-42E2-A604-D5144A7BC6B4@darmarit.de> Organization: LWN.net MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Sender: linux-kernel-owner@vger.kernel.org List-ID: X-Mailing-List: linux-kernel@vger.kernel.org Hi, Markus, I was glad to hear from you, but I have to agree with Jani: this is not how things are done. Consider this one line: > 706 files changed, 123369 insertions(+), 752 deletions(-) Something like that will be a huge red flag to any kernel maintainer! In the kernel community, we have spent the last 25 years figuring out a development model that is based on gradual, incremental changes, each of which can be reviewed on its own merits. It does *not* encompass wholesale replacements of existing code — even in situations where that code was not just merged after a year of discussions, negotiations, and false starts. I simply cannot accept this pull request. Markus, we all very much want your help in this work. You have expertise and energy that could really push the documentation effort forward. But it needs to be done the way kernel developers do it: cooperatively, incrementally, and always mindful of the entire community's needs. I would love it if you would take the flat-table and man-page work, separate them out, and make them work with the *existing* Sphinx-based scheme. If you can do it soon, we can maybe get it into 4.8. Can you focus on that for now, please? As for the rest, what we have now is certainly far from perfect; we're figuring a lot of this out as we go. Incremental improvements are welcome, and each will be evaluated independently. Please help us to make the kernel's documentation better that way. Thanks, jon