From mboxrd@z Thu Jan 1 00:00:00 1970 From: Alex Sassmannshausen Subject: Re: dmd: Some improvements to the dmd manual Date: Thu, 23 Jan 2014 16:09:40 +0100 Message-ID: <8761pau43v.fsf@gmail.com> References: <1390464950-5967-1-git-send-email-alex.sassmannshausen@gmail.com> <87r47yg7w1.fsf@gnu.org> Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit Return-path: Received: from eggs.gnu.org ([2001:4830:134:3::10]:33256) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1W6Lul-0005Nh-4W for guix-devel@gnu.org; Thu, 23 Jan 2014 10:10:03 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1W6Lua-0001VH-G2 for guix-devel@gnu.org; Thu, 23 Jan 2014 10:09:55 -0500 In-reply-to: <87r47yg7w1.fsf@gnu.org> List-Id: "Development of GNU Guix and the GNU System distribution." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: guix-devel-bounces+gcggd-guix-devel=m.gmane.org@gnu.org Sender: guix-devel-bounces+gcggd-guix-devel=m.gmane.org@gnu.org To: =?utf-8?Q?Ludovic_Court=C3=A8s?= Cc: guix-devel@gnu.org Hi Ludo, Ludovic Courtès writes: >> Let me know if you think I should ba approaching this differently. > > I will comment on the first patch, but what specific points do you want > to address more generally? Is it more about wording, structure, guiding > the user? (I can see some of that in the first patch.) It started of being about correcting typos and improving the wording a bit, but then it became about enhancing the journey of the reader a bit: make things friendlier where appropriate, keep things simpler, especially prior to chapter 2, etc. The manual that keeps coming back to me is the Geiser manual: it's written in a lovely way and I'd like to introduce some of its style whilst maintaining clarity and newbie-friendliness. I think the structure was pretty much defined in the old introduction (chapter 1: user; chapter 2 etc: advanced user; final chapter: hacking), and I like that structure so I would only be building on it I think. So, fixing typos and wording probably doesn't require large changes, guiding the user probably would imply some re-writing. I could split the job in two: always submit one patch fixing typos and wording, and then, if necessary, a rewritten section afterwards? (this might be slightly more work for me, but as there is no deadline that's fine :-). I like the style of the manual overall anyway, so I'm definitely approaching this with respect to what has been done already. Hope this clarifies my intentions a little — let me know if you want more info. Best wishes, Alex