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

[Valentin Sawadski]

Hello Joshua,

On Sat, 2007-11-24 at 08:14 -0500, Joshua Tauberer wrote:
> I think you're making it too complicated:
> 
>  >  - 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.
> 
> This just requires the addition of more tags to the documentation, one 
> that says when a member was removed.

I don't like that idea because this might introduce some since x,
removed in y, reintroduced in z.... patterns (Yes I know it is unlikely
but still possible)

>  >  - Automated user-contributions do not work properly (I don't know if a
>  >    contribution has ever made it into the documentation).
> 
> The current system isn't bad fundamentally. I think there's just some 
> personal overhead involved in Miguel taking the contributions and 
> applying them.

Is he still the only one in charge of the documentation approval?

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

Compared to the MS world it is really more complicated on mono. A simple
"/doc" compiler flag and running nDoc would suffice on windows.

> My two cents if you really want to address some of these things would be 
> to start on the UI side and make something that works "properly" with a 
> plain ZIP file of the XML documentation files, and no changes on the 
> server or mdassembler side. Once that works, if you need to cache some 
> indexes or whatever to be able to get to pages quickly, or if you need 
> changes to the XML documentation format, then look into that. A 
> documentation browser should be a simple program at its core.

Yes you are right the documentation browser should be as slim as
possible. However I still do think that the current xml-only approach
does not work sufficiently because of the limitations mentioned in my
first mail. A small database back-end could provide a lot more
opportunities for the creation and maintenance of documentation.

Kind Regards,
Valentin S.