[Mono-docs-list] Best way to contribute Mono documentation?
jonpryor at vt.edu
Tue Jan 19 14:10:30 EST 2010
On Mon, 2010-01-18 at 15:11 -0500, John Feminella wrote:
> However, I'm a little bit perplexed about the best place to start. The
> main Mono pages don't have much to say about the best way to
> contribute documentation or even the best way to get started with such
> contributions (e.g. "here's how to set up mdoc so that you can
> identify areas of spotty coverage" or "here's a link to our
> continuous-integration reports so that you can see which parts need
> working on"). I tried a few Google searches to this effect but still
> didn't turn up anything. (Did I miss a wiki page that has all this
There's a problematic history here; at one point in time (and currently,
afaik) you could edit documentation within the 'monodoc' GUI browser,
then upload those contributions via Contributing->Upload Contributions.
There are two problems with this: first, the monodoc editor sucks (at
least it does for me ), and second, we found that we had to manually
review all contributions, as very often people would copy & paste MSDN
documentation into monodoc and submit it. The review process is (of
course!) manual, was done by miguel, and, well, afaik it overtook him
The process hasn't changed; we need a better process, but at present no
one has had the time/inclination to create said better process
(especially a process that can properly deal with copy/paste issues).
It may very well be intractable, at least for BCL types.
Fortunately monodoc isn't the only way to write documentation...
> * Are contributions to the documentation currently being accepted?
Depends on how you contribute. :-)
As mentioned above, monodoc->Upload Contributions is currently a no-mans
However, if you have a mono checkout you can instead edit the XML
documentation directly. For example, Mono.Options XML documentation is
while Gtk# documentation is at:
For assemblies contained in mcs/class, documentation (if any) is kept in
Thus, if you have a source checkout, just edit the XML documentation
directly (or, if you're a glutton for punishment, use 'monodoc --edit';
see also ).
If you have commit access, you can then directly commit the docs (and
the web page will be updated...whenever I get around to rebuilding
them), or you can send a patch to the relevant mailing list to get them
As I have commit access, this is what I usually do, though I'll admit
this isn't really a solution for everyone (and likely greatly hinders
additional contributors, but since many of the "contributors" were
apparently violating MSDN copyright, that might not be such a bad
> * How should documentation patches be contributed, and to whom or
> where should they be e-mailed? What environment-configuration and
> patch-preparation steps should be undertaken to ensure smooth handoff?
If you directly edit the XML files as I suggest above, you'd need the
same environment as you would for building source (as most projects
bundle their documentation with their source, cf. Gtk#,
For Mono, this necessarily implies using svn, and then sending 'svn
diff' files to the mailing list for review. For Mono, it should be this
mailing list, mono-docs-list at lists.ximian.com.
One oddity I've noticed, though, is that 'svn diff' files generated on
Windows often won't apply to a Linux checkout. (At least, that's been
my experience...) I don't know of a decent workaround for this. :-/
> * What areas of Mono (or its related subprojects) documentation would
> provide the most value if they were completed?
Anything that isn't in the BCL (i.e. all Mono.* assemblies, namespaces,
and types). Given current copyright concerns, BCL is too large a
"target" for copy&pasters, so it's better to just ignore it, and rely on
MSDN as the canonical (and sole) documentation source. Mono.* types,
meanwhile, won't ever be documented at MSDN, so they need to be
> * Is there anything a prospective contributor should know before
> deciding what to help out on (e.g. "we have a major release on the
> horizon which will obsolete large swaths of documentation, including
> sections X, Y, and Z, so don't bother working on those")?
Don't document the internals of monodoc.dll. :)
Beyond that, you'd need to ask the actual maintainers of the assembly in
More information about the Mono-docs-list