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

[Joshua Tauberer]

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.

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

Yeah.

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

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

Fair point.

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

Maybe....

 >  - 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 documentation is under revision control in Subversion (though, you 
may mean you need something more explicit for deploying updates).

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.

You might also want to start by taking advantage of the monodocs2html 
stylesheet, which Jon has fixed up quite a bit for generics.

-- 
- Josh Tauberer

http://razor.occams.info

"Yields falsehood when preceded by its quotation!  Yields
falsehood when preceded by its quotation!" Achilles to
Tortoise (in "Gödel, Escher, Bach" by Douglas Hofstadter)


Valentin Sawadski wrote:
> 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.
> 
> _______________________________________________
> Mono-docs-list maillist  -  Mono-docs-list at lists.ximian.com
> http://lists.ximian.com/mailman/listinfo/mono-docs-list