From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED!not-for-mail From: Rocky Bernstein Newsgroups: gmane.emacs.devel Subject: Re: Realgud documentation: (Was: realgud now in elpa) Date: Mon, 8 Aug 2016 19:40:45 -0400 Message-ID: References: NNTP-Posting-Host: blaine.gmane.org Mime-Version: 1.0 Content-Type: multipart/alternative; boundary=94eb2c190b5efe82ce053997f156 X-Trace: blaine.gmane.org 1470699774 18414 195.159.176.226 (8 Aug 2016 23:42:54 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Mon, 8 Aug 2016 23:42:54 +0000 (UTC) Cc: emacs-devel@gnu.org To: rms@gnu.org Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Tue Aug 09 01:42:50 2016 Return-path: Envelope-to: ged-emacs-devel@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by blaine.gmane.org with esmtp (Exim 4.84_2) (envelope-from ) id 1bWuC1-0004hH-Bc for ged-emacs-devel@m.gmane.org; Tue, 09 Aug 2016 01:42:49 +0200 Original-Received: from localhost ([::1]:60882 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1bWuBy-0002z0-4M for ged-emacs-devel@m.gmane.org; Mon, 08 Aug 2016 19:42:46 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:54903) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1bWuA7-0002JM-2u for emacs-devel@gnu.org; Mon, 08 Aug 2016 19:40:52 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1bWuA5-0005K6-L1 for emacs-devel@gnu.org; Mon, 08 Aug 2016 19:40:51 -0400 Original-Received: from mail-ua0-x22b.google.com ([2607:f8b0:400c:c08::22b]:33133) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1bWuA3-0005JF-C3; Mon, 08 Aug 2016 19:40:47 -0400 Original-Received: by mail-ua0-x22b.google.com with SMTP id 74so92766663uau.0; Mon, 08 Aug 2016 16:40:47 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20120113; h=mime-version:sender:in-reply-to:references:from:date:message-id :subject:to:cc; bh=g3dktB+ddy4uE8XWf2x2VteiBMDxDOWupRZ+i2rGQfo=; b=AVaWmDUh63KT9tXTu5BIjRL1PBUNnzDbY0NU6XOM8pt2NjQT2/v/C7kF0ffxB5dNve KY5N3pq49LeFgMpwNTp++UjXHLXJcbCb6i85e3uV3cojdyAxAlxlhW/UTcYmwg7DGtbu YTSJTmXhcpRuhM1n4S8cCBEjozubj1klEgrpd46pUkgUUDABaDw+z7JniEHjzwlKodoq 3flmW066DBFjt3/M4LthD7jX/LI6VPZWn81mR9JC/AAhxazDp/RrjOnB6tMniIOeCuRg SqyvYoMIyk68s5uysyNXvJvjI9EgxF+43P6RLeZOWQ0sy6ChrbgUMJMftvcvQHWe+0/8 IkEA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20130820; h=x-gm-message-state:mime-version:sender:in-reply-to:references:from :date:message-id:subject:to:cc; bh=g3dktB+ddy4uE8XWf2x2VteiBMDxDOWupRZ+i2rGQfo=; b=YGjlA5KMN5aVXuy5zUXWfDZuPy7aABcsjYrQuNW7FB+n51RUNd7W+72kXErc6z4V2C RaCrKyZP0+shgPO1nFVnyrGRZlG5Mb978URAdUaTr1CGvckKDw76EzXD8lru2lkriNdg fL8C4qqFW+NZDq1slm7zctwOYng4GNS9420rtkl/xvn1lyhFilax38wjvvdPmOiWxr+g 10POyyxRSCu7LMz8SHQEhKXZhTIw8OgIHfk36as4GJS/QFZYTWrBPa+94n/lrGwq0TqO DajdgxVSEe8ZGEYefkeSifIxqCymzLv/zi8sBkXxYbLPIBgs1dDQzWxj4LHe1IXwTcFJ cZeg== X-Gm-Message-State: AEkoousaLfPRCOZYFkmVjJb5BmVixECE4MfcSjiW7D7dnV+Ejn9IIoaCuuO/xzNmQj7xtzguKy/K1QfjbMroQw== X-Received: by 10.176.80.229 with SMTP id d34mr17809233uaa.24.1470699646384; Mon, 08 Aug 2016 16:40:46 -0700 (PDT) Original-Received: by 10.103.81.77 with HTTP; Mon, 8 Aug 2016 16:40:45 -0700 (PDT) In-Reply-To: X-Google-Sender-Auth: KH-6ZqiEbbpAtFqTtsWbTmUD1c4 X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 2607:f8b0:400c:c08::22b X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.21 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Original-Sender: "Emacs-devel" Xref: news.gmane.org gmane.emacs.devel:206500 Archived-At: --94eb2c190b5efe82ce053997f156 Content-Type: text/plain; charset=UTF-8 On Mon, Aug 8, 2016 at 6:12 PM, Richard Stallman 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. > > --94eb2c190b5efe82ce053997f156 Content-Type: text/html; charset=UTF-8 Content-Transfer-Encoding: quoted-printable


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=C2=A0 =C2=A0 ]]]
[[[ whether defending the US Constitution against all enemies,=C2=A0 =C2=A0= =C2=A0]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]<= br>
I encourage people to give you the help you've asked for, but
I disagree with one point:

=C2=A0 > Don't know this particular package that well? Well, the bes= t way to
=C2=A0 > learn it is to start documenting what's there as
=C2=A0 > 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 be= came aware of that aspect of a good manual --=C2=A0 not just describing com= mands, but educating the reader -- as an avid reader of the GNU manu= als, 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 a= ny sort of comprehensive documentation

I was la= rgely thinking of this aspect.

This particular project w= as 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 d= ifferent 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 examp= le, some sort of multi-windows mode.

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

Wha= t's needed is someone who is interested to think of a good way t= o organize and present the information. From my past experience, in that pr= ocess a number of irregularities will likely be noticed and they can be fix= ed.



=C2=A0



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


--94eb2c190b5efe82ce053997f156--