On Tue, May 13, 2014 at 12:48 PM, Vikas Rawal <vikasli...@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 > >