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

[Søren Juul]

Hello

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



-- 
Med venlig hilsen / Kind Regards
Søren Juul
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.ximian.com/pipermail/mono-docs-list/attachments/20071124/64e18d8a/attachment.html