Re: Using Emacs, Org-mode and R for Research Writing in Social Sciences

[John Hendy <jw.hendy@gmail.com>]

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