[Mono-docs-list] Documentation, review.

Miguel de Icaza miguel@ximian.com
25 Aug 2002 01:09:24 -0400

Hello guys,

   I have been looking at the current framework we have for
documentation checked into CVS, and I think I would like to make a few
changes to the way documentation works.  Here are my thoughts:

	1. Assemblies should be each documented on its own, we should
	   not have a full merged set of documented.  

	   This way, we can use the same tools to document Gtk# and

	2. The merged "view" of all the documents should be taken care
	   at documentation install time, or by the GUI by importing
	   multiple documentation sources.

    I do not know where the templates we have right now came from: from
our assemblies or from the Microsoft assemblies.   The templates have a
number of problems: they are generated files, and hence, they are
subject to be overwritten in the future.

    What I would like for the "editing" tool, is a way to extract our
"target" documentation skeleton from the MS assemblies (we can probably
use CorCompare to do this), but this skeleton would not contain any
documentation, it would only be the skeleton.  

    The editing tool could then show which nodes are missing, and which
nodes have content.  We would only save actual content to our
documentation files, never stubs or pre-generated output.