[Mono-docs-list] State of Mono Documentation

[Mike Kestner]

Submitted for your reading pleasure, a dissertation on documentation.

As discussed during the holidays, I'm going to be joining the effort to
improve our documentation framework this year.  As maintainer of the
Gtk# documentation I am also a significant user.  In order to get the
ball rolling, I figured I would start by summarizing my perception of
the strengths and weaknesses of the current system, and then share my
current thoughts on how to improve it.  

I welcome your feedback.

=== Where we are ===

The foundation of the system is the monodoc XML format.  Building on an
XML document gives a nice base, with easy integration to existing source
management systems via plain text files, access to XSLT to produce
consumable content, and XML schemas for content validation.

Our format has remained stable and our transformation to HTML content is
fairly robust.  This has provided a nice viewing capability.  Web-based
content rendering is solid.  The offline rendering capability using
gecko or gtkhtml has been somewhat problematic of late.  The portability
of gecko and gtkhtml is currently an issue.  These appear to be
primarily packaging issues on linux distributions, but they also impede
the availability of local documentation viewing on Windows and Mac. 

The document maintenance side is not as rosy as the viewing side,
however.  The fragmentation of the system into numerous tools makes it
challenging to use.  There is no online editing/contribution capability,
and the offline editing capability built in to the browser is not
WYSIWYG.  The contribution mechanism requires manual intervention
introducing an administration bottleneck.

Despite these limitations, we have had many community contributors to
the documentation, for which we are grateful.  It is unclear how much
the above limitations have impacted the potential contributor base, but
they certainly aren't helping matters, and they are impacting the
productivity of the existing contributor base and maintainers.

The document validater lists several TODO items in the header which
appear significant.  Being solely schema-based, it also lacks features
like <see> element reference validation.  Integrating it into a
documentation editor for on-the-fly validation would be another big
gain.

Document updating/stubbing is done via the monodocer tool.  The tool is
fairly robust, but can be very noisy.  For example, I have frozen at an
old revision of monodocer in Gtk# because of some changes which
generated an avalanche of "whitespace" into the Gtk# documents like
reordering of member nodes.  These types of issues just add churn to the
change management footprint, and make it hard to distinguish real
changes from noise in a project the size of Gtk#.

A typical documentation session for me in Gtk# looks something like
this:

1) Run monodocer via a make target, since I can never remember the
monodocer command switches I need.  Read through the diff and commit
whitespace changes resulting from the use of conflicting XML writers in
tools like the contributions admin tool, one of my Gtk# automated signal
documenters, or from internal changes to monodocer itself.

2) Edit a monodoc xml file with vim to fill in stubs for recent API
changes.  I manually add markup and crefs by memory, usually with only
partial success on the markup and memory front.

3) Maybe run the validater if I think of it, but usually not.  I guess I
could improve the frequency by adding it to one of the make targets...

4) Run the assembler via a make target.

5) Fix any reported markup issues, make && make install to my private
monodoc prefix and run monodoc to see if I got the crefs right.

6) Fix all the crefs I got wrong, and then commit.

7) Wait for the next monodoc release or Gtk# release, or Miguel's next
manual push of the resulting docs to the website to have the new
documents show up for users.

I mention number 7 since documentation in many cases should not
necessarily be tied to product release schedules.  For Gtk# and the mono
class libs, if a documentation change is accepted into the change
management system it probably ought to be user-visible immediately if it
validates.  This could be considered a Mono/Gtk# process issue, but it
would be nice to have infrastructure to facilitate faster documentation
publishing than the glacial speed of software releases.

In summary, we have a lot of room for improvement in our documentation
production environment.

=== Where we could go ===

Since my elbow hurts from casting stones, I'll offer some thoughts on
how I'd like to see the system improved.

On-line editing of documentation is an intriguing idea which has been
discussed in the past.  The technology would essentially be focused on
enticing users to fill in stubs in existing documentation.  While this
is a nice idea, I'm not convinced in the return on investment.  It also
would do little to help maintainers add documentation for new API to
existing catalogs.  

I want to focus instead on the offline side to put better tools in the
hands of library authors and project teams.  My ultimate goal would be
to integrate monodocer, validater, and assembler into a WYSIWYG editor
and documentation administration tool.  That rather large goal can be
segmented into several intermediate milestones.

First milestone would be a WYSIWYG editor for the monodoc XML format.
It would be written as a thin wrapper app around a few custom widgets: a
catalog tree widget to navigate a document catalog directory tree, and
one or more document views to edit a given XML document.  The document
views would probably be DrawingArea subclasses utilizing inserted
TextViews for editing.  

These widgets could be exposed as a library for use by a standalone
editor as well as a MonoDevelop plugin for project documentation.  The
doc view could be used in an inert mode to display external
documentation.  This library would resolve the portability issues of the
existing html widgets.

Once the above widgets are complete, I would probably move next to
integrated validation and assembly, and providing a completion-like
capability for <see> elements, like what you get typing in a source
editor in a modern IDE.  Validation would be completely under the hood,
notifying the user immediately when they do something that fails
validation and assembly. 

The next milestone would be integrating monodocer functionality into the
editor.  My vision for this is to associate a set of assemblies with a
documentation catalog, and instead of generating stub documentation in
the catalog directory itself, the editor could identify undocumented
types and members in a special pane or tree node.  

It would also tag superfluous documentation for removal.  At this point,
the assembler would be fully integrated into the tool as well, so any
necessary stubs needed for an assembled doc catalog could be generated
on the fly instead of putting them out on disk and into the change
management system.

=== On Contributions and Review ===

Documentation review is not much like code review.  Unfortunately,
that's what we've got right now.  Reviewing a contributed documentation
patch is an exercise in scanning XML markup.  My understanding is that
the web service admin tool has a rendered diff capability, but I'd like
to see this capability integrated into the documentation editor.

I want to be able to open a diff, see a marked up version of the change
complete with spell checking, and merge it to my tree if it looks good.
That would be sweet.  This capability will be useful for organizations
with a formal documentation review process.  They usually need to
distribute change-highlighted formatted documentation in print or
electronic form to reviewers.

=== On Updates ===

Catalog updating would be a cool capability to add to the offline viewer
so that users could opt to receive updates to installed catalogs when
they are connected.  We could have a web service interface to advertise
the current revision stamp and provide patch downloads to requesting
clients.

The web service could also be configured with repository information so
that it could pull documentation updates from the change management
system, so that live or at least periodic batch updates of the
documentation catalog could be pushed.  This could also remove the
manual interaction required to update an online web catalog.
 
=== Final Thoughts ===

I was going to invest a few paragraphs here heading off likely
questions, opinions, and criticisms here, but you are probably tired of
me already, so if you made it this far...

Thanks for reading, I await your feedback.

-- 
Mike Kestner <mkestner at novell.com>