[Mono-docs-list] Proposing a new documentation subsystem
zpon.dk at gmail.com
Sat Nov 24 10:52:42 EST 2007
I like your proposal, especially the part about user contributions and
comments (I believe they could help many people).
But i think a database on the client side would be much work, and make it
more difficult to import new documentation library's, although it could be
Maybe I am wrong, if so, please correct me...
2007/11/24, Valentin Sawadski <valentin.sawadski at gmx.de>:
> 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
> Apart form adding documentation to the class libraries this tool
> 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
Med venlig hilsen / Kind Regards
-------------- next part --------------
An HTML attachment was scrubbed...
More information about the Mono-docs-list