mono/web/documentation

* Documentation

	Although most of the concepts from Microsoft.NET can
	be applied to the completed Mono platform, we do need to
	have a complete set of free documentation written specifically
	for Mono.

	The documentation license we have chosen is the GNU Free
	Documentation License (FDL), the standard for most documents
	in the free software world. 

	We need documentation on a number of topics:

	<ul>

		* The development tools (compilers, assembler tools,
		  language reference, design time features): these
	          live in the `monodoc' CVS module.

		* Frequently Asked Question compilations.

		* HOWTO documents.

		* The Class Libraries (Both the original .NET class
	 	  libraries as well as the class libraries produced by
		  the project).

		* Tutorials on Mono and the specifics of running it
		  (The <a href="http://www.monohispano.org">Mono
		  Hispano</a> team has produced lots of <a
		  href="http://www.monohispano.org/tutoriales.php">tutorials
		  in spanish</a>

		* A guide to Mono as compared to the Microsoft.NET
		  Framework SDK

	</ul>

* Class Library documentation

	We are moving to a new setup for documenting the class libraries, 
	and you can read about it <a href="classlib-doc.html">here</a>.

	There are two classes of documentation: free documentation for
	existing .NET classes and documentation for the classes that
	we have developed on top of .NET.

	There is a large body of documentation that came from the ECMA
	standarization effort that has been checked into CVS.  It does
	not contain everything Mono and .NET have, so they need to be
	updated and augmented.

** Gtk# documentation

	We also have a large body of class libraries that are specific
	to Mono, for example the documentation for Gtk#.  

	We have checked in stub documentation for Gtk# into the CVS
	repository (on gtk-sharp/doc) and we need volunteers to help
	populate the documentation for it.  Since Gtk# is a wrapper
	for Gtk, plenty of documentation exists in the <a
	href="http://developer.gnome.org/doc/API">Gnome developer
	site</a>.

	To get started:

	You need to download Gtk# from the CVS repository.  The module
        name is `gtk-sharp'.  You can obtain a copy from both the CVS
        repository or the anonymous CVS repository.

        To pull your copy type:

<pre>
        	cvs co gtk-sharp
</pre>
        Documentation lives in gtk-sharp/doc/en.  The "en" indicates the
        English language, the first one we are targeting.  We can later
        do translations, but for now we are focusing on a single
        language.

        In that directory you will find the documentation organized by
        namespaces.  One directory per namespace.  In the directories
        you will find one XML file per class that needs to be
        documented.  The mission is to fill in the data with useful
        information.  Feel free to grab liberally information from the
        Gtk documentation from:

       	<a href="http://developer.gnome.org/doc/API/">http://developer.gnome.org/doc/API/</a>

        Of course, the API does not apply directly.  It only applies at
        a foundational level, so you can not really just copy and
        paste.  Summaries, and remarks sections can probably be lifted
        with little or no effort.

        Gtk# uses properties to represent get/set operations in the C
        API, so you can also use some bits from there.

        Most of the documentation contains already place holders for
        text, we use the internationally approved phrase for this
        purpose, `To be added'.  So the quest is to remove all of the
        "To be added" strings with information with resembles as closely
        as possible the toolkit reality.

*** The pieces to be filled.

        Summaries are one or two line descriptions of the element
        (class, struct, interface, method, field, event, delegate), and
        its used to render summary pages.  So it has to be short.
        
        The "remarks" section is used to describe in detail the element.

**** Tags.
        
        As you document Gtk# you will have a number of tags that you can
        use inside the summary and remarks sections, these are:

<pre>        
&lt;para&gt; &lt;/para&gt;
</pre>
        	Used to separate paragraphs.
      
<pre>  
&lt;paramref name="param_name"/&gt;
</pre>
        	Used to reference a formal parameter to a function.

<pre>  
&lt;see cref="T:SomeTypeName"/&gt;
</pre>
        	Use this to reference a type, this will include an hyper
        	link to the page for type SomeTypeName.

        	For example, to reference "System.Enum", do:
        
<pre>
	&lt;see cref="T:System.Enum"/&gt;
</pre>

<pre>
&lt;see cref="P:SomeTypeName.Property"/&gt;
</pre>
        	Use this to reference a property, this will include an hyper
        	link to the page for the property `Property' of type `SomeTypeName'.

        	For example, to reference the BaseType property in System.Type, do:
        
<pre>
	&lt;see cref="P:System.Type.BaseType"/&gt;
</pre>

<pre>
&lt;see cref="M:SomeTypeName.Method(type,type)"/&gt;
</pre>
        	Use this to reference a method, this will include an hyper
        	link to the page for the method `Method' of type `SomeTypeName'.
        
        	For example, to reference the ToString method in System.Object, do:
        
<pre>
	&lt;see cref="M:System.Object.ToString()"/&gt;
</pre>
        
<pre>
&lt;see langword="keyword"/&gt;
</pre>
        	Use this to link to a keyword in the C# language, for
        	example to link to `true', do:

<pre>
	&lt;see langword="true"/&gt;
</pre>
        
<pre>
&lt;example&gt; ... &lt;/example&gt;
</pre>        
        	Use example to insert an example.  The example can 
        	contain explanatory text and code.
        
<pre>
&lt;code lang="C#"&gt;.. &lt;/code&gt;
</pre>
        
        	Use this to provide a sample C# program, typically used
        	within the &lt;example&gt; tags.

        	When providing examples, try to provide a full example,
        	we would like to be able to have a button to compile and
        	run samples embedded into the documentation, or pop up
        	an editor to let the user play with the sample.

        	You can link to an example like this:

<pre>
	&lt;code lang="C#" source="file.cs"&gt; &lt;/code&gt;
</pre>

<pre>
&lt;item&gt;
</pre>
        	
<pre>
&lt;list type="bullet"&gt;  &lt;/list&gt;
</pre>
        
        	Use this to create lists.  Lists contains &lt;item&gt;
        	elements which have to contain &lt;term&gt; containers.
        
<pre>
&lt;list type="table"&gt; &lt;/lits&gt;
            &lt;listheader&gt;
              &lt;term&gt;YOUR FIRST COLUMN&lt;/term&gt;
              &lt;description&gt;YOUR DESCRIPTION&lt;/description&gt;
            &lt;/listheader&gt;
</pre>
        	For two-column tables.  Inside use:
        
<pre>
&lt;item&gt;
	&lt;term&gt;First&lt;/term&gt;
	&lt;description&gt;First descritpion&lt;/description&gt;
&lt;/item&gt;
&lt;item&gt;
	&lt;term&gt;Second&lt;/term&gt;
	&lt;description&gt;Second descirption&lt;/description&gt;
&lt;/item&gt;
</pre>

** Words of warning.

        A few words of warning and advice for class documentors:

        A well-documented API can ease hours of frustration; as Mono
        matures, robust and complete class library documentation will
        become increasingly important.  As you write API documentation,
        whether it is embedded in source files or in external Monodoc XML,
        please keep the following in mind:

        Plagarism, even if it's unintentional, is a Bad Thing(TM).
        Microsoft's .NET Framework Class Library documentation is an
        excellent resource for understanding the behavior and properties of
        a type, and a lot of hard work went in to creating this (copyrighted)
        resource.  Please don't copy from Microsoft's reference when
        documenting a type.

        To avoid this, I (<a href="mailto:[email protected]">[email protected]</a>)
        suggest that you read the complete Microsoft documentation for a type,
        ponder it for a while, and write the Mono documentation in your own
        words.  While it's certainly okay to refer to the Microsoft
        documentation to clarify your understanding of behavior or properties,
        please don't open the Microsoft docs and refer to them for each member
        you document.

	The best way of documenting is to read our source code
	implementation and explain in your own words what our implementation
	does, and what the user can do with it.

        There's a lot of domain expertise among the class library contributors;
        let's put the same personal stamp on the class library documentation
        that we have on the class libraries themselves.