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