From: Hongli Lai Date: 2008-08-15T01:18:05+09:00 Subject: Re: Documenting DSLs Thomas Sawyer wrote: > Actually I don't see anything very special about this. > That's not to > say it's not well done. But it's just a markup format (Asciidoc) > wrapped in an ERB based template tool. That's fairly easy to whip > together. Plus, why use a Python-based markup tool when we have RD and > Markdown (among others) for Ruby? > > RDoc ties code to docs, it's an API documentor, not just a format > transformation system. But maybe your point is that coupling is a > waste of time, and we should just write our docs to be processed > indifferent to any relation to code? > > T. It is often said that Ruby projects lack narrative documentation. Documenting individual DSL methods will not be very helpful to people who are new to the DSL. New developers will want narrative, introductory texts with lots of examples, especially when they don't know which DSL method to look at in the first place. RDoc and similar tools are good for API reference-style documentation, but less suitable for narrative documentation. Consider for example the documentation for a typical Perl module. It usually contains both narrative text, as well as reference-style documentation. This is made possible by the fact that Perl documentation format, POD, allows free-style documentation. There is no enforced structure, so that the author can write the documentation in whatever way he thinks is best. Asciidoc allows this. It allows one to structure documentation in any way he wants, in a syntax that's still clearly readable and easily writable. Asciidoc can be converted to many formats, including HTML, Unix man pages and PDF. For example, the Git documentation is written in Asciidoc. It is for these reasons that I think the Asciidoc format is ideal for documenting DSLs. Furthermore, it is my opinion that not only the documentation content is important, but also its presentation. A nicely formatted and visually pleasing document invites people to read it. It makes the documentation less boring, so people will be able to read the contents faster and be able to remember the contents better. Indeed, Mizuho isn't very special, but its goal is to make good-looking HTML output for Asciidoc documents and not to be special. Mizuho/Asciidoc provide the following things that are not found in Markdown for example: - Syntax highlighting. This makes example code easier to read, and more visually pleasing. - Multi-page output. If your document is long, then having everything on a single page can be quite annoying and can make the document hard to navigate. - Many formatting options, including definition lists, tables, images with captions, note/tip/warning/caution paragraphs, etc. As for Python being used, I don't really see the problem. Personally I don't care what language a tool is written in, as long as it gets the job done. I don't think rewriting Asciidoc in Ruby is worth the investment. -- Posted via http://www.ruby-forum.com/.