News for hackers. Stuff that matters.
Re:WTFM - Write The Freaking Manual by orangethirty on Friday September 28, 2012 @08:58AM (#4585247)
You can run the source through one of those automated documentation tools like doxygen. That does make a big difference.
Re:WTFM - Write The Freaking Manual by threedaymonk on Friday September 28, 2012 @09:23AM (#4585338)
Honestly, I'm not sure it does. I've seen plenty of software projects whose documentation consists of an automated compendium of every method in every class, none of which tells me how to actually use it.

I'd prioritise a simple getting started guide. It only has to be a page or so, but something that explains how to run the program, and achieve a few simple tasks. It's far easier to go from a simple case to a more complicated case than it is to go from nothing to even a simple case.

To pick on a specific project, Treetop http://treetop.rubyforge.org/ has a pretty detailed set of documentation (human-generated, not automated), but I found it quite hard to go from the abstract enumeration of its features to actual working code. So hard, in fact, that I wrote up an introduction to help others, and it's been a very popular page: http://po-ru.com/diary/getting-started-with-treetop/

Re:WTFM - Write The Freaking Manual by nathan_long on Friday September 28, 2012 @10:08AM (#4585567)
+1. If I wanted to rummage through a pile of classes and methods to figure out where to start, I'd just read the code.

I want a conceptual overview, usage examples, and some discussion of edge cases.

I've rabidly documented my Rails authorization library, and I'd attribute most of the attention it's gotten to the documentation.

https://github.com/nathanl/authority