Realgud documentation: (Was: realgud now in elpa)

Realgud documentation: (Was: realgud now in elpa)

[Rocky Bernstein]

[-- Attachment #1: Type: text/plain, Size: 1465 bytes --]

T.V Raman reports:

> > s/melpa/elpa/  and for the record, most packages installed via the
> > package manager be it elpa or melpa come with almost no documentation.

and rms advises:

*> It is important to write documentation for them.  How about asking*
>


* the authors of some packages to write manuals for them?*

I totally agree. A good deal of the software I write in fact has
extensive documentation. See for example:
https://www.gnu.org/software/libcdio/libcdio.html,
http://bashdb.sourceforge.net/bashdb.html,
http://bashdb.sourceforge.net/ruby-debug.html for texinfo-style
documentation and
http://python2-trepan.readthedocs.io/en/latest/
for non-texinfo style.

But in this particular case, for various reasons, it will probably be
a while before I undertake to write any sort of
comprehensive documentation in texinfo format.

However, I invite others to start with what's there in the github wiki
<https://github.com/realgud/realgud/wiki> and the README.md that is
provided in elpa,
and turn that into texinfo. And I'll be happy to include that in the
installation.

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.

There are also plenty of docstrings that describe functions. And if
you have a question about something,
just contact me and I will be happy to assist or review documentation.

In sum, turn your passion for good documentation into something tangible.

[-- Attachment #2: Type: text/html, Size: 2005 bytes --]

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

[Richard Stallman]

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



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

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

[Rocky Bernstein]

[-- Attachment #1: Type: text/plain, Size: 1982 bytes --]

On Mon, Aug 8, 2016 at 6:12 PM, Richard Stallman <rms@gnu.org> 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.
>
>

[-- Attachment #2: Type: text/html, Size: 3149 bytes --]

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

[Richard Stallman]

[[[ 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 agree with what you've said.

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