| If that's all you want, Anarki already has it. ^_^ I'm interested in finding a documentation solution that scales up to programming-in-the-large, without being the cumbersome kind of thing that people would have trouble using even if they wanted to. This discussion about Racket's documentation woes is pretty thought-provoking: http://www.mail-archive.com/dev@racket-lang.org/msg00957.htm... In particular, I like the Racket approach of having both an API reference, where people look up the meanings of particular functions, and a user guide, where people learn the design of the system and develop a better idea of which functions they should actually be looking for. In-source docstrings (or Javadoc comments and the like) should be an okay way to get good coverage in the API reference, but they're kinda independent of each other and hard to automatically organize, especially in a language without modules or classes. They're not even close to being good pieces for walkthrough-like user guides. Literate programming, meanwhile, encourages code to be arranged as though it's a user guide. (This may be just one style of literate programming; I imagine people who care about literate programming mainly just care about good documentation.) The Inform 7 docs are an awesome example of this: http://inform7.com/sources/inweb/ http://inform7.com/sources/src/stdrules/Woven/index.html However, there are usually at least some parts of the code that are left as an exercise for the reader to understand. :-p This approach also straddles the line between guide and reference without necessarily being the best at either. There's kind of a cross-cutting concern going on, the more roles you try to give to a single codebase, and it kinda drives me in the reverse of literate programming: I almost suspect it would be most ideal just to put nothing but implementation notes in the code comments, and to have code be simple enough to stand on its own (like the current state of Arc). This ties back in with another, more important part of the Racket discussion: The version of the program you have shouldn't determine the version of the docs you have. In fact, the docs oughta be a living document that immediately collects improvements and discussions, oftentimes faster than the codebase changes. They should be some form of wiki or help forum. I'll go farther than that: Keeping comments in the code is a brittle system because they'll become inconsistent with the real docs. Instead, people should browse the code on a website that automatically lets them see the most recent versions of the wiki content. There'd essentially be a CMS that manages: - The code itself. - Snippet-local API docs. - Comprehensive, listing-like API references. - User guides. - Examples of various sizes (like aw's "pastebin for examples" idea). - Tutorials. - Bug tracking entries. - Freeform discussions on all these things. This is bigger than I expect to design all by myself, for sure. :-p | 
