From mboxrd@z Thu Jan 1 00:00:00 1970 From: ludo@gnu.org (Ludovic =?utf-8?Q?Court=C3=A8s?=) Subject: Re: dmd: Some improvements to the dmd manual Date: Fri, 24 Jan 2014 13:52:28 +0100 Message-ID: <87ppnhk0dv.fsf@gnu.org> References: <1390464950-5967-1-git-send-email-alex.sassmannshausen@gmail.com> <87r47yg7w1.fsf@gnu.org> <8761pau43v.fsf@gmail.com> Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable Return-path: Received: from eggs.gnu.org ([2001:4830:134:3::10]:40048) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1W6gKJ-0006w6-1C for guix-devel@gnu.org; Fri, 24 Jan 2014 07:57:46 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1W6gKB-00030m-NO for guix-devel@gnu.org; Fri, 24 Jan 2014 07:57:38 -0500 Received: from hera.aquilenet.fr ([141.255.128.1]:41491) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1W6gKB-00030b-Fs for guix-devel@gnu.org; Fri, 24 Jan 2014 07:57:31 -0500 In-Reply-To: <8761pau43v.fsf@gmail.com> (Alex Sassmannshausen's message of "Thu, 23 Jan 2014 16:09:40 +0100") 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: Alex Sassmannshausen Cc: guix-devel@gnu.org Hello Alex, Alex Sassmannshausen skribis: > Ludovic Court=C3=A8s 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. Sounds good! > 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. That=E2=80=99s a good benchmark. :-) > 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 think splitting into two parts here would be annoying for you, and not very fruitful if large parts are going to be rewritten anyway. So submit in whatever form is the most appropriate for you: split by section when that=E2=80=99s possible, and otherwise whatever you think make= s a consistent change set. > 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 It does, and I like the ideas. Thank you! Ludo=E2=80=99.