* Documentation
- A project like Mono will require a lot of documentation to be
- written. Although most of the concepts from Microsoft.NET can
- be applied to the Mono platform once finished, we do need to
- have a complete set of free documentation written for it.
+ 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 FSF FDL which
- is the standard for most documents on the free software
- world.
+ 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 to be written on a number of topics:
+ We need documentation on a number of topics:
+
+ <ul>
* The development tools (compilers, assembler tools,
language reference, design time features).
- * Freely redistributable Frequently Asked Question
- compilations.
+ * Frequently Asked Question compilations.
- * Freely redistributable HOWTO documents.
+ * HOWTO documents.
* The Class Libraries
- * Tutorials on Mono and the specifics of running it
- compared to the Microsoft.NET Framework SDK
-
- * Differences between the Microsoft.NET Framework SDK
- development mode and the Mono version.
+ * Tutorials on Mono and the specifics of running it.
-** Class Library documentation
+ * A guide to Mono as compared to the Microsoft.NET
+ Framework SDK
- When contributing to the Class Library effort, please use the
- inline XML documentation tags to document your classes so we
- can automatically generate the documentation from the class
- libraries.
-
- If you provide examples, please do not embed them into the
- source code, as that will make the source code harder to read
- and maintain. Instead put examples for your code into a
- subdirectory of the class libraries. Also make that sample
- code a full standalone application that people can compile
- (ideally our documentation browser could let you edit, modify
- and run the sample programs, as Tcl/Tk used to let you do in
- the past).
+ </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>.
+
+ 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:jbarn@httcb.net">jbarn@httcb.net</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.
+
+ 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.
\ No newline at end of file
projects / mono.git / blobdiff