10Experience

Scribble is part of the PLT Scheme distribution as of version
4.0, which was released in June 2008, and all PLT Scheme documentation
is created with Scribble. Developing Scribble, porting old PLT Scheme
documentation, and writing new documentation took about a year, but
the @ notation evolved earlier through years of
experimentation.

The documentation at http://docs.plt-scheme.org/ is
built nightly by Scribble from a snapshot of the PLT Scheme source
repository. The same documentation is available in PDF form at
http://pre.plt-scheme.org/docs/pdf/. At the time of this
writing, the 70 PDF files of current documentation total 3778 pages in
a relatively sparse format, which we estimate would fit in around 1000
pages if compressed into a conference-style, two-column layout. This
total includes documentation only for libraries that are bundled with
PLT Scheme; additional libraries for download via PLaneT are also
documented using Scribble.

PLT Scheme documentation was previously written in LaTeX and
converted to HTML via tex2page (Sitaram2007). Although
tex2page was a dramatic improvement over our original use of
latex2html, the build process relied on layers of fragile
LaTeX macros, HTML hacks, and pre- and post-processing scripts,
which made the documentation all but impossible to build except by its
authors. Consequently, most library documentation used a plain-text
format that was easier to write but inconsistent in style and
difficult to index. The documentation index distinguished identifier
names from general terms, but it did not attach a source module
to each identifier name, so online help relied on textual search.

The Scribble-based documentation system is accessible to all PLT
Scheme users, who write their own documentation using Scribble and
often supply patches to the main document sources. Scribble produces
output that is more consistent and easier to navigate than the old
documentation, and the resulting documentation works better with
online help. More importantly, the smooth path from API documentation
to stand-alone documents has let us produce much more tutorial
and overview documentation, helping users find their way through
the volumes of available information.