THIS IS A WORK IN PROGRESS!
This is the source for the documentation published on MonoGame.net. It is rebuilt when the code changes and is published nightly to the website.
First some general rules one should follow when contributing documentation to the MonoGame project.
- Write in a neutral technical tone at all times.
- Avoid humor, personal opinions, and colloquial language.
- Never plagiarize any documentation from another source.
- Automatic documentation tools are useless.
Breaking these rules can result in your contribution being rejected.
TODO!
- Fork the MonoGame repo.
- Create a branch to work from.
- Use the GitHub markup editor from the browser.
- Submit pull requests early and often.
Before you contribute any documentation you should learn a bit about what we expect out of the different types of documentation.
TODO!
The API reference documentation is a big part of the documentation effort for MonoGame. The documentation is written in the C# XML format and is inline to the MonoGame source code. The final web pages with API documentation are generated using SharpDoc.
In the reference documentation every word should strive to provide additional information beyond the API itself. If the documentation only rehashes or rephrases what is already apparent in the class, method, parameter, or property name it has zero value and will only waste the time of both the writer and reader.
There is no guarantee that the reader will read beyond the first sentence of the reference documentation. This is why that first sentence is the most important and should convey the most key piece of information. Take your time to write the most concise and clear first sentence possible. This helps users tremendously and goes a long way towards having great documentation.
Surface Information Hidden In the Code
Being inline with the code allows you to easily look for critical information within it that the user might not know from looking at the API alone. Take your time to explore inner method calls and platform specific sections of the code. The time to write the documentation is once you feel you fully understand the code you are documenting. If you don't feel you understand the code then leave the documentation for someone else to write.
Remember that the user is searching for an answer for a specific question. It is your job to predict these questions and provide them clear answers.
All documentation contributed to the MonoGame project is subject to the Creative Commons Attribution-NonCommercial-ShareAlike license. By contributing you are agreeing to the terms of that license.
MonoGame Documentation by the MonoGame Team is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike License.
