Re: Realgud documentation: (Was: realgud now in elpa)

[Rocky Bernstein]

On Mon, Aug 8, 2016 at 6:12 PM, Richard Stallman <address@hidden> wrote:

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

I encourage people to give you the help you've asked for, but
I disagree with one point:

  > Don't know this particular package that well? Well, the best way to
  > learn it is to start documenting what's there as
  > you go along.

A good manual is not just a description of the features, but rather a
description of the best way to use them, and that often includes things
that experienced users figure out.

I became aware of that aspect of a good manual --  not just describing commands, but educating the reader -- as an avid reader of the GNU manuals, especially those solely written by, or co-authored by, rms.

So when I wrote:

for various reasons, it will probably be a while before I undertake to write any sort of comprehensive documentation

I was largely thinking of this aspect.

This particular project was written, as I suppose many are, out of my particular personal needs and desires. I have come to learn that my needs and use this package are very different from many others.

So although I have gotten drawn in along the way by needs and desires of others, they are often not mine. For example, some sort of multi-windows mode.

For these reasons, I am not qualified to write the kind good documentation I think is needed.

What's needed is someone who is interested to think of a good way to organize and present the information. From my past experience, in that process a number of irregularities will likely be noticed and they can be fixed.

 

--
Dr Richard Stallman
President, Free Software Foundation (gnu.org, fsf.org)
Internet Hall-of-Famer (internethalloffame.org)
Skype: No way! See stallman.org/skype.html.