[Mono-docs-list] Proposing a new documentation subsystem

[Miguel de Icaza]

>  - Insufficient support for "Multi-Version" files (e.g. Class-Libs
>    from .NET 1.1 and 2.0) because the current "Since Version X.Y" does
>    not work if a member is only available in 1.1 and not in 2.0.

I can not think of an example, but even if I did, you could still add
the comment as a regular remark.

>  - Generic Types and Members are not fully supported in the
>    documentation browser.

This is a bug, should be easy to fix.

>  - Automated user-contributions do not work properly (I don't know if a
>    contribution has ever made it into the documentation).

Thousands have.    There are a number of problems though:

	* Am currently the only admin.

	* There are few contributions, fewer good ones.

	* Many of the contributions are bad (incomplete examples,
	  non-compiling examples, lack of consistency in the examples),
	  description is sometimes plain wrong.

	* Some of the contributions for Gtk# tend to be cut-and-paste
	  without any editing or adjustments for Gtk# directly from the
	  Gtk+ docs.

	* Worst of all: for the MS APIs, many contributions are direct
	  cut and paste texts from the MSDN documentation.

	  This last one means that I tend to defer their approval until
	  I have visually inspected each documentation member, and this 
	  takes a lot of time.

	  If the contribution is minor, I usually let it go.

>  - Even if documentation has been updated the updates won't make it back
>    to the user before a new version of mono has been released. (With
>    other words, there is no way to update offline-documentation)

Correct;   But there is so little documentation being written, that this
is not a major issue.

If we had people writing lots of documentation, we could upload new zip
files and have monodoc ping those to download them.

Today, adding such support would be mostly useless, considering the
glacial speed at which people actually write docs.

>  - Documentation work-cycle is pretty complicated. It is very unhandy to
>    run many tools to do one simple task. (monodoc, browser, mdassembler)

Not sure what you mean.

>  - No Revision control (this is not a big turn-off however it would be
>    quite handy when user-contributions will finally work) and no user
>    comments (again not very important but nice to have)

We have revision control, its called SVN.


> The Server Part would mainly be used for data-storage and contribution
> handling. A simple web-service which is backed by some db would be quite
> sufficient. For Contribution-administration and adding of new assemblies
> to the documentation service a simple web-ui should suffice.

We already have this, the admin UI could be improved, and I can grant
other people admin rights;   The problems with the contributions
remains.

As usual, programmers tend to think that they can code their way out of
actually writing documentation.   And as it turns out, writing
documentation, requires someone to sit down and go through the
implementation and actually describe it.   No amount of tooling helps
here.

I would be happy to improve the documentation tools though, and am
looking for some concrete, but most importantly evolutionary proposals
as opposed to revolutionary ones.

Miguel