Develop Documentation Guidelines

[tomspilman]

We need to develop a set of guidelines for users helping with MonoGame API reference documentation.

The guidelines should include some simple bullet points as to things documentation writers should address in class, method, and parameter docs.

It should also include examples of bad and good docs which illustrate what we want to see and what we don't want to see in the MonoGame docs.

The guide should be maintained in the wiki.

[tomspilman]

A few references which we can use to develop our own guidelines:

http://www.monperrus.net/martin/how-to-write-good-API-documentation
http://msdn.microsoft.com/en-us/magazine/gg309172.aspx
http://theamiableapi.com/2011/11/01/api-design-best-practice-write-helpful-documentation/

[darkling3100]

I definitely think that a very short bit of example code should be included just to see the basic usage of the method and a short clear explanation of the parameters. Also a string possibly somewhere at the top of the needed "#using" statement.

[tomspilman]

very short bit of example code

Putting sample code into the inline reference docs is pretty hard to do, but I agree that examples are important. At the very least the reference docs could link to examples of use that can be shared for multiple methods. I just don't know how that would work in the C# XML doc format.

[darkling3100]

Well I'm not to sure how you would feel about adding samples individually per page, if doing it through the wiki (which would be a hell of a job), but I think that's the only way to get clearly defined examples. But yeah I don't think there would be any way to add examples inline and still keep code "cleanliness."

[totallyeviljake]

I have to agree with @tomspilman about being able to supply useful sample code in the XML summary on a method. There are two segments of code in MonoGame. One is the low level platform code and the other is the XNA interface code. The XNA interface code should not require extensive documentation since it has a broad internet following already. The low level code will only be interfaced with "expert" level programmers who will be reading code rather than using a binary distro. For those reasons, I don't think we really need any code samples in the XML summaries. Just make sure the algorithm in the method is documented and the parameters are clearly documented with boundary conditions.

[darkling3100]

Very true, no point in righting hundreds of more lines of text when most is already documented.

[KonajuGames]

Miguel would like us to use monodoc for documentation. We can import the
existing xmldoc into monodoc, and we can supply sample code sections in
monodoc. This is something that I have to look into.

[kentcb]

Never used monodoc before, but when using SHFB you can "import" working, compiling, regions of code into your XML doc as examples. I used that here, for example. Perhaps monodoc has something similar?

[tomspilman]

I'm going to address this soon. Will add a README.md into the new Documentation folder which will contain instructions on how to help work on the docs as well as some examples of good and bad docs.

[tomspilman]

Took a first stab at the guidelines...

https://github.com/mono/MonoGame/blob/develop/Documentation/README.md

... could use some feedback on it.

[danzel]

Looks like a good start, I don't see any issues with what's in there so far :)

[tomspilman]

Thanks!