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

[Valentin Sawadski]

Hello everybody,

let's remove the dust from this list again ;-)

Today I would like to propose a new documentation subsystem to
completely replace the old one.

Because replacing seems like such a big step I would like to explain why
I want to abolish it:
 - 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.
 - Generic Types and Members are not fully supported in the
   documentation browser.
 - Automated user-contributions do not work properly (I don't know if a
   contribution has ever made it into the documentation).
 - 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)
 - Documentation work-cycle is pretty complicated. It is very unhandy to
   run many tools to do one simple task. (monodoc, browser, mdassembler)
 - 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)

The new documentation subsystem should be able to fulfill all
requirements above. This means the new documentation subsystem would
consist of a user and server part.

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.

The Client part however will be more important. It will also have a
small SQLite-DB which contains all the data for offline availability.
This data will be updated with new documentation from the server
regularly.
	Apart form adding documentation to the class libraries this tool will
also support 3rd party assemblies. It should be possible to add
libraries or existing documentation to the client application which can
than be easily documented. For distribution of the documentation I was
thinking of two possibilities:
 1. it should be able to export the documentation of the 3rd party
    assembly to a single file (probably again a SQLite-DB). Users can
    than xcopy the exported file into some directory so that this db
    will also be displayed in their browser.
 2. If 3rd party developers set up their own documentation server it
    would be very neat if users get a URL to that server and then
    "check-out" a copy of the documentation for offline availability.

If this subsystem will be designed very nicely this will give 3rd party
developers also the ability to set-up a documentation browser as well so
that they can also benefit from user-contributed documentation.

Hopefully I was able to communicate my ideas well enough and now I'm
looking forward to some comments :-)

Kind Regards,
Valentin S.