From: Eli Zaretskii <eliz@gnu.org>
To: Dmitry Gutov <dgutov@yandex.ru>
Cc: rgm@gnu.org, michael.albinus@gmx.de, emacs-devel@gnu.org
Subject: Re: Docstrings and manuals
Date: Mon, 18 Apr 2016 05:30:16 +0300 [thread overview]
Message-ID: <83k2jvabt3.fsf@gnu.org> (raw)
In-Reply-To: <532e9505-ea1b-d035-e5c6-131ec36ea441@yandex.ru> (message from Dmitry Gutov on Sun, 17 Apr 2016 22:59:21 +0300)
> Cc: michael.albinus@gmx.de, rgm@gnu.org, emacs-devel@gnu.org
> From: Dmitry Gutov <dgutov@yandex.ru>
> Date: Sun, 17 Apr 2016 22:59:21 +0300
>
> > IOW, writing a good manual is still a human activity that cannot be
> > easily automated. Ideally, doc strings should be phrased like
> > reference material, covering all the traits as tersely as possible,
> > while the manual should provide an easier reading with more continuity
> > text and even some explanations why things are the way they are. At
> > least IMO.
>
> That sounds fine, and maybe this way is best for the more complex
> subjects, but in general I'd prefer to see docstrings also written with
> readability in mind.
This would make them too long ad wordy, something we'd like to avoid,
I think.
next prev parent reply other threads:[~2016-04-18 2:30 UTC|newest]
Thread overview: 53+ messages / expand[flat|nested] mbox.gz Atom feed top
[not found] <6ok2vyzwf9.fsf@fencepost.gnu.org>
[not found] ` <08f70cda-44be-0657-e50a-2b2c80d2c21c@yandex.ru>
[not found] ` <87oa9dzgl0.fsf@gmx.de>
[not found] ` <bbdc2630-f791-dace-15d0-c1e73d8c88fc@yandex.ru>
[not found] ` <87potshczh.fsf@gmx.de>
[not found] ` <e3132bc6-f1d4-ebef-00d4-93fa0807fea0@yandex.ru>
[not found] ` <87h9f4ghzg.fsf@gmx.de>
[not found] ` <ec924912-8098-c824-0583-bed1e7150074@yandex.ru>
[not found] ` <8737qnc8ep.fsf@gmx.de>
2016-04-17 0:17 ` Docstrings and manuals, was: Re: bug#20637: incompatible, undocumented change to vc-working-revision Dmitry Gutov
2016-04-17 8:49 ` Docstrings and manuals Michael Albinus
2016-04-17 10:50 ` Dmitry Gutov
2016-04-17 11:16 ` Michael Albinus
2016-04-17 11:42 ` Dmitry Gutov
2016-04-17 12:19 ` Michael Albinus
2016-04-17 13:12 ` Dmitry Gutov
2016-04-17 15:14 ` Eli Zaretskii
2016-04-17 16:39 ` Michael Albinus
2016-04-17 19:39 ` Dmitry Gutov
2016-04-17 15:12 ` Eli Zaretskii
2016-04-17 19:59 ` Dmitry Gutov
2016-04-18 2:30 ` Eli Zaretskii [this message]
2016-04-18 12:55 ` Phillip Lord
2016-04-18 15:35 ` Marcin Borkowski
2016-04-18 15:47 ` Stefan Monnier
2016-04-18 16:30 ` Marcin Borkowski
2016-04-18 18:56 ` Eli Zaretskii
2016-04-18 19:33 ` Stefan Monnier
2016-04-18 19:39 ` Eli Zaretskii
[not found] ` <<83ziss9sml.fsf@gnu.org>
2016-04-17 15:54 ` Drew Adams
2016-04-17 15:03 ` Eli Zaretskii
2016-04-17 15:15 ` Dmitry Gutov
2016-04-17 16:23 ` Eli Zaretskii
2016-04-17 20:22 ` Dmitry Gutov
2016-04-18 2:33 ` Eli Zaretskii
2016-04-18 8:38 ` Richard Stallman
2016-04-18 9:50 ` Dmitry Gutov
2016-04-19 0:25 ` Richard Stallman
2016-04-19 7:59 ` Dmitry Gutov
2016-04-19 23:51 ` Richard Stallman
2016-04-18 14:55 ` vc-state and unregistered (was: bug#20637: incompatible, undocumented change to vc-working-revision) Michael Albinus
2016-04-18 21:11 ` vc-state and unregistered Dmitry Gutov
2016-04-19 8:10 ` Michael Albinus
2016-04-19 8:21 ` Dmitry Gutov
2016-04-19 8:31 ` Michael Albinus
2016-04-19 8:43 ` Dmitry Gutov
2016-04-24 12:11 ` Michael Albinus
2016-04-24 12:21 ` Dmitry Gutov
2016-04-24 12:45 ` Michael Albinus
2016-04-24 12:49 ` Dmitry Gutov
2016-04-24 13:07 ` Michael Albinus
2016-04-24 13:13 ` Dmitry Gutov
2016-04-24 13:24 ` Michael Albinus
2016-04-24 13:27 ` Dmitry Gutov
2016-04-24 14:03 ` Michael Albinus
2016-04-24 17:23 ` Dmitry Gutov
2016-04-24 17:35 ` Dmitry Gutov
2016-04-24 18:13 ` Michael Albinus
2016-04-24 18:58 ` Dmitry Gutov
2016-04-24 19:41 ` Michael Albinus
2016-04-24 20:43 ` Dmitry Gutov
2016-04-24 13:08 ` Dmitry Gutov
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: https://www.gnu.org/software/emacs/
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=83k2jvabt3.fsf@gnu.org \
--to=eliz@gnu.org \
--cc=dgutov@yandex.ru \
--cc=emacs-devel@gnu.org \
--cc=michael.albinus@gmx.de \
--cc=rgm@gnu.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://git.savannah.gnu.org/cgit/emacs.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).