Re: dmd: Some improvements to the dmd manual

[ludo@gnu.org (Ludovic Courtès)]

Hello Alex,

Alex Sassmannshausen <alex.sassmannshausen@gmail.com> skribis:

> 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.

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’s 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’s possible, and otherwise whatever you think makes 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’.