From: John Hendy <jw.hendy@gmail.com>
To: Vikas Rawal <vikaslists@agrarianresearch.org>
Cc: org-mode mailing list <emacs-orgmode@gnu.org>
Subject: Re: Using Emacs, Org-mode and R for Research Writing in Social Sciences
Date: Tue, 13 May 2014 13:15:05 -0500 [thread overview]
Message-ID: <CA+M2ft9SokrY+uCmUA0ZXxSqa8qs0+8zoCiE=jG_Fb-gDN9FWw@mail.gmail.com> (raw)
In-Reply-To: <B0130C52-B969-421A-BA9C-620CAB8F8D94@agrarianresearch.org>
On Tue, May 13, 2014 at 12:48 PM, Vikas Rawal
<vikaslists@agrarianresearch.org> wrote:
>
>
>> Aloha Vikas,
>>
>> Very nice!
>>
>> Your document overlaps and updates the LaTeX export tutorial on Worg
>> that I wrote for the old exporter. Perhaps it could be revised to
>> replace the old export tutorial?
>
> There is some overlap. But I think there is a considerable utility in addressing people who would need to be taken from installation of emacs to production of a full document.
My 0.02 cents on this. As someone who often leans quite far toward the
verbose/thorough end of the spectrum, I completely relate to this
sentiment. That said, I've come to believe it's sub-optimal. With this
approach, what ends up happening is:
- Multiple versions of the same information proliferate (we're
re-doing each other's work)
- Similarly, there's more information to update down the road
- While excellent/to-your-best-knowledge, the instructions you provide
might not be the best ones
Thus, I've started to believe how you approached the initial sections
(install Emacs, R, Org) are better. A sentence or two, with a link to
do the thing you're telling them to do. While it probably /won't/
happen (at least with the vast majority of those options), what if
this page changes?
- http://orgmode.org/manual/Export-settings.html
You now have to update your table of various options as well. Even
without that... I'm no longer convinced of the benefits of re-writing
existing documentation for the sake of an all-in-one information
source, unless it's a book (meant to be standalone).
It seems safer/efficient to focus on making modular documentation that
is the definitive *best*/*right* way (and *best* explained) to do
something, and then to link to that prolifically.
This feels horrible to write, as your document looks awesome. You did
ask for feedback, and things migrated toward this area, so I wanted to
flesh out why I think one might steer toward one approach vs. another.
That said, as long as it isn't incorrect... more documentation is
still almost always better to increase the probability of finding the
right hit on Google, so thanks a ton for your contribution and effort
to help others.
Best regards,
John
>
> That is, people start using a workable solution, and then go to more detailed documentation to modify it to their needs and to learn rest of the stuff that you can do with Org.
>
> I could, however, tweak it specifically for Worg depending on what is considered most appropriate for Worg.
>
> Vikas
>
>
next prev parent reply other threads:[~2014-05-13 18:15 UTC|newest]
Thread overview: 26+ messages / expand[flat|nested] mbox.gz Atom feed top
2014-05-12 12:57 Using Emacs, Org-mode and R for Research Writing in Social Sciences Vikas Rawal
2014-05-12 13:26 ` Suvayu Ali
2014-05-12 19:36 ` Vikas Rawal
2014-05-12 21:00 ` Thomas S. Dye
2014-05-13 17:48 ` Vikas Rawal
2014-05-13 18:15 ` John Hendy [this message]
2014-05-13 18:40 ` Vikas Rawal
2014-05-14 14:19 ` Suvayu Ali
2014-05-14 16:02 ` Vikas Rawal
2014-05-13 19:55 ` Thomas S. Dye
2014-05-13 18:01 ` Eric S Fraga
2014-05-13 18:52 ` Vikas Rawal
2014-05-14 3:38 ` Using Emacs, Org-mode and R for Research Writing in Social Sciencess Ken Mankoff
2014-05-14 7:00 ` Vikas Rawal
2014-05-14 9:02 ` Christopher Witte
2014-05-14 10:15 ` Vikas Rawal
2014-05-14 13:23 ` Ken Mankoff
2014-05-14 13:27 ` Vikas Rawal
2014-05-14 13:27 ` Vikas Rawal
2014-05-14 14:07 ` Using Emacs, Org-mode and R for Research Writing in Social Sciences Axel Kielhorn
2014-05-14 16:51 ` Vikas Rawal
2014-05-14 18:39 ` Axel Kielhorn
2014-05-15 4:49 ` Vikas Rawal
2014-05-15 8:18 ` Axel Kielhorn
2014-05-15 8:38 ` Vikas Rawal
2014-05-15 11:57 ` Axel Kielhorn
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.orgmode.org/
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to='CA+M2ft9SokrY+uCmUA0ZXxSqa8qs0+8zoCiE=jG_Fb-gDN9FWw@mail.gmail.com' \
--to=jw.hendy@gmail.com \
--cc=emacs-orgmode@gnu.org \
--cc=vikaslists@agrarianresearch.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/org-mode.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).