Re: dmd: Some improvements to the dmd manual

[Alex Sassmannshausen]

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