[Mono-docs-list] Best way to contribute Mono documentation?

[Jonathan Pryor]

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
> somewhere?)

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 [0]), 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
ages ago.

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
land.

However, if you have a mono checkout you can instead edit the XML
documentation directly.  For example, Mono.Options XML documentation is
at:

        http://anonsvn.mono-project.com/source/trunk/mcs/class/Mono.Options/Documentation/en/
        
while Gtk# documentation is at:

        http://anonsvn.mono-project.com/source/trunk/gtk-sharp/doc/en/

For assemblies contained in mcs/class, documentation (if any) is kept in
mcs/class/[ASSEMBLY]/Documentation/en.

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 [0]).

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
committed.

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
thing).

> * 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#,
mcs/class/*/Documentation directories).

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
documented.

> * 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
question.  Sorry.

 - Jon

[0]
http://www.jprl.com/Blog/archive/development/mono/mdoc/2010/Jan-10.html