web/documentation

   1 * Documentation
   2
   3         Although most of the concepts from Microsoft.NET can
   4         be applied to the completed Mono platform, we do need to
   5         have a complete set of free documentation written specifically
   6         for Mono.
   7
   8         The documentation license we have chosen is the GNU Free
   9         Documentation License (FDL), the standard for most documents
  10         in the free software world.
  11
  12         We need documentation on a number of topics:
  13
  14         <ul>
  15
  16                 * The development tools (compilers, assembler tools,
  17                   language reference, design time features).
  18
  19                 * Frequently Asked Question compilations.
  20
  21                 * HOWTO documents.
  22
  23                 * The Class Libraries
  24
  25                 * Tutorials on Mono and the specifics of running it.
  26
  27                 * A guide to Mono as compared to the Microsoft.NET
  28                   Framework SDK
  29
  30         </ul>
  31
  32 ** Class Library documentation
  33
  34         We are moving to a new setup for documenting the class libraries,
  35         and you can read about it <a href="classlib-doc.html">here</a>.
  36
  37         A few words of warning and advice for class documentors:
  38
  39         A well-documented API can ease hours of frustration; as Mono
  40         matures, robust and complete class library documentation will
  41         become increasingly important.  As you write API documentation,
  42         whether it is embedded in source files or in external Monodoc XML,
  43         please keep the following in mind:
  44
  45         Plagarism, even if it's unintentional, is a Bad Thing(TM).
  46         Microsoft's .NET Framework Class Library documentation is an
  47         excellent resource for understanding the behavior and properties of
  48         a type, and a lot of hard work went in to creating this (copyrighted)
  49         resource.  Please don't copy from Microsoft's reference when
  50         documenting a type.
  51
  52         To avoid this, I (<a href="mailto:jbarn@httcb.net">jbarn@httcb.net</a>)
  53         suggest that you read the complete Microsoft documentation for a type,
  54         ponder it for a while, and write the Mono documentation in your own
  55         words.  While it's certainly okay to refer to the Microsoft
  56         documentation to clarify your understanding of behavior or properties,
  57         please don't open the Microsoft docs and refer to them for each member
  58         you document.
  59
  60         There's a lot of domain expertise among the class library contributors;
  61         let's put the same personal stamp on the class library documentation
  62         that we have on the class libraries themselves.