From: Trans <transfire@...>
Date: 2008-08-16T21:24:48+09:00
Subject: Re: Documenting DSLs



On Aug 14, 12:18 pm, Hongli Lai <hon...@phusion.nl> wrote:

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

You make an excellent argument.

While I still think it would be nice if an API documentation tool for
Ruby could better handle DSLs, I agree that narrative documentation
should get more focus.

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

Sure. But as a Rubyists, I prefer Ruby solutions when they are
available.

T.