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

John Feminella johnf.pub at distb.net
Wed Jan 20 00:26:54 EST 2010

Thanks very much for that info, Jonathan; it was immensely helpful. I
hope you won't mind if I follow up with a few clarifying questions:

> 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/

* Are these source and not generated files? That is, it was my
understanding is that things in a path matching **/Documentation/**
are generated by an external documentation-generation tool. If someone
later updated the source, wouldn't that cause problems with the
resulting generated files? Is this a mistaken view?

So, to me it sounds like the take-away conclusion to draw from your
earlier e-mail are:

* Don't use `monodoc --edit`.

* Do use `mdoc update` + documentation stubs.

* Maybe use inline XML + `mdoc update -i MyType.xml`.

* Chug out docs by filling out the stubs mdoc generates. You can use
`mdoc export-html` to see how it all looks once you're making

* Find an assembly or two (or perhaps even an ancillary project like
Cadenza) and just jump right on it, mailing relevant patches to the
appropriate committers as needed.

Is that about the gist of it?

~ jf

John Feminella
Principal Consultant, Distilled Brilliance

On Tue, Jan 19, 2010 at 14:10, Jonathan Pryor <jonpryor at vt.edu> wrote:
> 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

More information about the Mono-docs-list mailing list