[Mono-docs-list] Guidelines to help build the class library documentation

[Jonathan Pryor]

On Sun, 2008-06-22 at 21:16 -0700, visor wrote:
> I've been looking lately at the mono documentation on the mono website and
> even when the msdn documentation is, most of the time, enough for mono
> users, I think we should have our own documentation build since many users
> see this lack of documentation as a reason to avoid using mono and keep
> themselves "safe" in the microsoft version of the platform.

I'm not sure how often this is actually the case.  One of the nicer
points is that you can use existing .NET documentation while developing
on mono, including the dozens of existing books and everything else.
I'm not sure that we need to duplicate all of that work.

> I would really like to contribute to documentation since this is one of the
> most important points in a project to be succesful but, how do we get
> started? I can see there are a lot of methods and classes not documented,
> classes and methods that any .Net user expect to be documented (read:
> anything below System.*) and as I said before, most would tell me that we
> should just go to msdn but then again, I feel we should really have our
> documentation so it could be shipped with the distribution of the mono
> platform.

Then there's the size argument.  Just for the types that have been
stubbed out in monodoc -- which does NOT include all assemblies shipped
with mono - there are 63276 members on 6652 types.  Any such
documentation effort will be *massive*.

I'm not saying "Don't Do This," but I'm trying to point out how much
work you're looking at here.

Particularly since, by and large, few people enjoy writing documentation
(says the guy who wrote ~all of the Mono.Posix and Mono.Unix docs, and
Mono.Fuse, and NDesk.Options, and I do NOT enjoy writing docs...).

> Why there's so much lack of documentation? Is there some copyright issue on
> the Microsoft documentation that denies users to use that as a base to build
> documentation?

Yes.  MSDN is copyright Microsoft, and we have no rights to reuse any
part of MSDN.

Microsoft has granted us the ability to reuse the docs that are included
in the ECMA standard, which is pretty much why we have *any*
documentation for any System.* types (says the guy who wrote the ECMA
documentation importer...).

But ECMA != MSDN, and I doubt that Microsoft would permit us to bundle
anything outside of ECMA.

Though perhaps we should ask to be sure... :-)

>  I ask this because i believe many of their documentation
> could be used to build the mono documentation, maybe not copying and pasting
> but at least taking the examples and following mono documentation
> guidelines.

Examples would also have a Microsoft copyright, and thus couldn't be
included unless they permitted it.

> Any place to start? I've read the guidelines but could not find anything
> about that.

For the time being, I would *strongly* encourage NOT trying to write
documentation for anything that MSDN already has.

Instead, concentrate on writing docs for assemblies NOT in .NET, e.g.
the "Mono Libraries" tree in monodoc, possibly including Mono.GetOptions
(though perhaps not, as Mono.GetOptions is deprecated), Mono.Math.*,
Mono.Remoting.Channels.Unix, Mono.Security, Mono.Xml...

Sure, ideally we could provide full documentation in monodoc, but given
the size of the team we have (~0), that's just not going to happen.
Which is why we should focus on providing docs for types not covered by
MSDN, so that they can be used by others with minimal effort.

 - Jon