[Mono-dev] Current state of documentation?

[Joshua Tauberer]

For future reference, mono-docs-list is the right place for these
questions.  (Anyone replying should now reply on that list and not
mono-devel-list.)  On to my reply:

Hi, Brian,

Brian Crowell wrote:
> I've checked out the monodoc project from AnonSVN, but I'm not sure if
> it's being used. The contents of the various XML files don't match those
> on the website, unless there's some special translation for anything
> marked "To be added".

Actually, there is.  Miguel pointed out some time ago that "To be added"
made it seem like the implementation, rather than the documentation, is
missing.  So it replaces that on the fly with whatever it actually says.

Sometimes the web version falls out of date with what's in SVN, but that
should be the only difference.

> 1. What is being used from this project, and should it be updated in its
> present form?

The monodoc documentation should be updated, yes.

We're waiting (or at least I was) for Cecil to support generics before
documenting the .NET 2.0 libraries.

> 2. Who is currently watching over this?

Miguel, from the official side of things, but various other people on
mono-docs-list have stepped up to watch over things as well.

> 3. Would it be helpful (and/or legal) to update the Mono doc set with
> the documentation from the ECMA specs? (I can't find a notice from the
> ECMA site that says either way.) If not, what other way could the
> documentation for the base classes be updated?

Unless the ECMA docs have been released under an open-source-ish
license, they're copyrighted and can't be 'imported' without permission
from the copyright holder.  I don't know if they're licensed at all.

The other way to update docs is for people to write them. :)  Really,
the best people to write docs are the people that have had a hand in the
implementation of the class libraries.  (Nudge nudge.)  But the rest of
us really ought to do some writing too, either through the Monodoc Gtk#
app, or via editing the XML files directly and committing or submitting
a patch to mono-docs-list.

-- 
- Joshua Tauberer

http://taubz.for.net

"Unfortunately, we're having this discussion. It's too bad,
because guess who listens to the discussion: the enemy."