dmd: Some improvements to the dmd manual

dmd: Some improvements to the dmd manual

[Alex Sassmannshausen]

Hello,

I'm assuming that dmd contributions go to the guix list for now.

Attached a patch introducing some changes to the dmd manual — the
patch only covers the Introduction section for now as I wanted to
submit something with my approach early to know whether it is
acceptable.

As you can see it's a bit of a rewrite, but I think the English is
overall easier to understand.

Let me know if you think I should ba approaching this differently.

Best wishes,

Alex

[PATCH] Doc: Introduction: rewrite for style and clarity.

[Alex Sassmannshausen]

* dmd.texi (Introduction): Rewrite for style and clarity.
---
 dmd.texi |   52 ++++++++++++++++++++++++++++------------------------
 1 file changed, 28 insertions(+), 24 deletions(-)

diff --git a/dmd.texi b/dmd.texi
index 841ce7c..4e06e93 100644
--- a/dmd.texi
+++ b/dmd.texi
@@ -78,24 +78,28 @@ the GNU system.
 
 @cindex service manager
 This manual documents the @dfn{dmd} service manager.  It is used to
-start and stop system services (typically daemons).  It ensures that
-this will work---by automatically starting services that are needed for
-another service to run and avoiding that conflicting services are
-started at the same time.  It does so in a very flexible way.  dmd is
-the @dfn{init system} on the GNU system---the first user process that is
-started when the system boots, typically with PID 1, running as
-@code{root}, and taking care of system-wide services.  It is also a
-useful tool that assists unprivileged users in the management of their
-own daemons.
-
-As with all flexible software, it takes some work to learn how to use
-it.  To make it as easy as possible for you, this manual contains a
-chapter that enables you to start using dmd without reading about all
-the details first @ref{Jump Start}.  The second chapter @ref{deco and
-dmd} describes the programs in detail.  The other chapters provide a
-reference with examples, where all possibilities that dmd provides are
-explained.  An exception is the last chapter, which contains
-information for those brave enough to modify dmd itself.
+start and stop system services (typically daemons) in a reliable
+fashion---by automatically starting prerequisites (``required
+services'') and by preventing conflicting services from being started.
+dmd is designed to be flexible when choosing what services to start
+and stop.
+
+dmd is the @dfn{init system} of the GNU operating system---it is the
+first user process that gets started, typically with PID 1, and runs
+as @code{root}. Normally the purpose of init systems is to manage all
+system-wide services, but dmd can also be a useful tool assisting
+unprivileged users in the management of their own daemons.
+
+Unfortunately all flexible software requires some time to master and
+dmd is no different.  But don't worry: this manual should allow you to
+get started quickly. Its first chapter is designed as a practical
+introduction to dmd and should be all you need for everyday use
+(@ref{Jump Start}).  In chapter two (@ref{deco and dmd}) we will
+describe the deco and dmd programs, and their relationship, in more
+detail.  The chapters following chapter 2 provide a full reference
+manual and plenty of examples, covering all of dmd's capabilities.
+Finally, the last chapter provides information for those souls brave
+enough to hack dmd itself.
 
 The name dmd stands for @dfn{Daemon Managing Daemons} (or
 @dfn{Daemons-Managing Daemon}?).
@@ -105,12 +109,12 @@ The name dmd stands for @dfn{Daemon Managing Daemons} (or
 @cindex GOOPS
 This program is written in @dfn{Guile}, an implementation of the
 Scheme programming language, using the @dfn{GOOPS} extension for
-object-orientation, therefore Guile is also used as the language for
-the configuration (@pxref{Top,,, guile, GNU Guile Reference Manual}).
-When you want to make use of advanced features of
-dmd, you should know how to work with Guile and GOOPS, but it has been
-tried to make using basic features of dmd possible without knowing how
-to program in Scheme at all.
+object-orientation. Guile is also dmd's configuration language
+(@pxref{Top,,, guile, GNU Guile Reference Manual}).  We have tried to
+make dmd's basic features as accessible as possible---you should be
+able to use these even if you do not know how to program in Scheme.  A
+basic grasp of Guile and GOOPS is required only if you wish to make
+use of dmd's more advanced features.
 
 @c @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
 
-- 
1.7.9.5

Re: [PATCH] Doc: Introduction: rewrite for style and clarity.

[Ludovic Courtès]

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

> * dmd.texi (Introduction): Rewrite for style and clarity.

Overall looks good to me!

A few comments below:

> --- a/dmd.texi
> +++ b/dmd.texi
> @@ -78,24 +78,28 @@ the GNU system.
>  
>  @cindex service manager
>  This manual documents the @dfn{dmd} service manager.  It is used to

[...]

> +start and stop system services (typically daemons) in a reliable
> +fashion---by automatically starting prerequisites (``required
> +services'') and by preventing conflicting services from being started.
> +dmd is designed to be flexible when choosing what services to start
> +and stop.

I prefer to avoid parenthetical expressions in the middle of sentences,
because it breaks the rhythm when reading the sentence.

Perhaps that can be achieved here by adding a sentence before to
introduce “services” and “prerequisites”?

> +dmd is the @dfn{init system} of the GNU operating system---it is the
> +first user process that gets started, typically with PID 1, and runs
> +as @code{root}. Normally the purpose of init systems is to manage all
> +system-wide services, but dmd can also be a useful tool assisting
> +unprivileged users in the management of their own daemons.

Currently the manual says “It is also a useful tool that assists
unprivileged users in the management of their own daemons.”  I think it
would be nice to keep that information somewhere, though I agree it
sort-of gets in the way currently.  WDYT?

> +Unfortunately all flexible software requires some time to master and
> +dmd is no different.  But don't worry: this manual should allow you to
> +get started quickly. Its first chapter is designed as a practical
> +introduction to dmd and should be all you need for everyday use
> +(@ref{Jump Start}).  In chapter two (@ref{deco and dmd}) we will

Use @pxref for parenthetical cross-references (info "(texinfo) @pxref").

> +describe the deco and dmd programs, and their relationship, in more

@command{deco} and @command{dmd}.

> +detail.  The chapters following chapter 2 provide a full reference
            ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

“Subsequent chapters”?

> +manual and plenty of examples, covering all of dmd's capabilities.
> +Finally, the last chapter provides information for those souls brave
> +enough to hack dmd itself.

I like the distinction you make between essential for normal use,
advanced use, and hacking.

Fine point: please use two spaces after an end-of-sentence period.

Thank you!

Ludo’.

(unknown),

[Alex Sassmannshausen]

Hello,

Please find, following on from this, a further revision of the patch
for dmd's manual, taking into account Ludovic's feedback.

Best wishes,

Alex

[PATCH] Doc: Introduction: rewrite for style and clarity.

[Alex Sassmannshausen]

* dmd.texi (Introduction): Rewrite for style and clarity.
---
 dmd.texi |   53 +++++++++++++++++++++++++++++------------------------
 1 file changed, 29 insertions(+), 24 deletions(-)

diff --git a/dmd.texi b/dmd.texi
index 841ce7c..a970894 100644
--- a/dmd.texi
+++ b/dmd.texi
@@ -78,24 +78,29 @@ the GNU system.
 
 @cindex service manager
 This manual documents the @dfn{dmd} service manager.  It is used to
-start and stop system services (typically daemons).  It ensures that
-this will work---by automatically starting services that are needed for
-another service to run and avoiding that conflicting services are
-started at the same time.  It does so in a very flexible way.  dmd is
-the @dfn{init system} on the GNU system---the first user process that is
-started when the system boots, typically with PID 1, running as
-@code{root}, and taking care of system-wide services.  It is also a
-useful tool that assists unprivileged users in the management of their
-own daemons.
-
-As with all flexible software, it takes some work to learn how to use
-it.  To make it as easy as possible for you, this manual contains a
-chapter that enables you to start using dmd without reading about all
-the details first @ref{Jump Start}.  The second chapter @ref{deco and
-dmd} describes the programs in detail.  The other chapters provide a
-reference with examples, where all possibilities that dmd provides are
-explained.  An exception is the last chapter, which contains
-information for those brave enough to modify dmd itself.
+start and stop system services (typically daemons) in a reliable
+fashion.  For instance it will dynamically determine and start any
+other services that our desired service depends upon.  As another
+example, dmd might detect conflicts between services.  In this
+situation it would simply prevent the conflicting services from
+running concurrently.
+
+dmd is the @dfn{init system} of the GNU operating system---it is the
+first user process that gets started, typically with PID 1, and runs
+as @code{root}.  Normally the purpose of init systems is to manage all
+system-wide services, but dmd can also be a useful tool assisting
+unprivileged users in the management of their own daemons.
+
+Unfortunately all flexible software requires some time to master and
+dmd is no different.  But don't worry: this manual should allow you to
+get started quickly.  Its first chapter is designed as a practical
+introduction to dmd and should be all you need for everyday use
+(@pxref{Jump Start}).  In chapter two we will describe the
+@command{deco} and @command{dmd} programs, and their relationship, in
+more detail (@ref{deco and dmd}).  Subsequent chapters provide a full
+reference manual and plenty of examples, covering all of dmd's
+capabilities.  Finally, the last chapter provides information for
+those souls brave enough to hack dmd itself.
 
 The name dmd stands for @dfn{Daemon Managing Daemons} (or
 @dfn{Daemons-Managing Daemon}?).
@@ -105,12 +110,12 @@ The name dmd stands for @dfn{Daemon Managing Daemons} (or
 @cindex GOOPS
 This program is written in @dfn{Guile}, an implementation of the
 Scheme programming language, using the @dfn{GOOPS} extension for
-object-orientation, therefore Guile is also used as the language for
-the configuration (@pxref{Top,,, guile, GNU Guile Reference Manual}).
-When you want to make use of advanced features of
-dmd, you should know how to work with Guile and GOOPS, but it has been
-tried to make using basic features of dmd possible without knowing how
-to program in Scheme at all.
+object-orientation.  Guile is also dmd's configuration language
+(@pxref{Top,,, guile, GNU Guile Reference Manual}).  We have tried to
+make dmd's basic features as accessible as possible---you should be
+able to use these even if you do not know how to program in Scheme.  A
+basic grasp of Guile and GOOPS is required only if you wish to make
+use of dmd's more advanced features.
 
 @c @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
 
-- 
1.7.9.5

Re: [PATCH] Doc: Introduction: rewrite for style and clarity.

[Ludovic Courtès]

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

> * dmd.texi (Introduction): Rewrite for style and clarity.

Pushed, thanks!

Please add a copyright line for yourself (assuming you’re the copyright
holder) in dmd.texi in the next commit.

Ludo’.

Re: dmd: Some improvements to the dmd manual

[Ludovic Courtès]

Hi!

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

> I'm assuming that dmd contributions go to the guix list for now.

Yep.

> Attached a patch introducing some changes to the dmd manual — the
> patch only covers the Introduction section for now as I wanted to
> submit something with my approach early to know whether it is
> acceptable.
>
> As you can see it's a bit of a rewrite, but I think the English is
> overall easier to understand.

Yes, that makes sense.

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

Thank you!

Ludo’.

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

Re: dmd: Some improvements to the dmd manual

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