Call to improve the documentation using XNA documentation

[mrhelmut]

Even though MonoGame is a verbatim re-implementation of Microsoft's XNA 4, we were not allowed to reproduce XNA's API documentation.

We now have the authorization from Microsoft to use the former official XNA documentation for use in MonoGame's documentation, including the API documentation and blog articles, as long as we mention © 2012 Microsoft Corporation. All rights reserved. wherever we use any of it (#7798 is already taking care of the legal mention, so contributions to the documentation shouldn't have to bother about this).

This is an opportunity to refresh the API documentation of MonoGame, as well as writing more in-depth documentation articles.

Any kind of help in that regard is more that welcome and is likely a very good way to contribute for the first time.

The documentation articles source can be found here and are written in markdown format.
The API documentation source is within the API itself, and generated from the actual C# source code using XML documentation.

[ghost]

Could tutorials for beginners be written please?

[aquagoose]

There are many out there.
The ones from RB Whittaker are quite well known.

[BlueElectivire]

Although there are tutorials on the internet, I think that it could be very useful to have something more in-depth on the official website, because the current getting started page is quite barebones and doesn't use a lot of the basic parts of the framework like GameComponents.
Imo, the website should ideally be able to get you started with the relevant idiomatic workflow, and expose you to most stuff you need to get going, not just how the update draw loop works.

[mrhelmut]

I intend to open another issue to call to contribute tutorials/upgrade existing tutorials to MG 3.8.1.

We're launching a broader project to make video tutorials.

[mrhelmut]

Please check this issue for tutorials. This present issue is only to discuss articles and the API documentation. (Articles are kind of linked to tutorials, especially the getting started section, but not quite, so let's have a separate discussion here about them.)

[yariker]

Any chance you could also generate XML documentation for IntelliSense and include it into the NuGet package?

[dmars8047]

Is there some way to preview the generated documentation changes locally? It would be nice to be able to spot check that as I go.

[mrhelmut]

I would suggest a visual markdown editor like Marktext.

[dmars8047]

@mrhelmut cool, thanks so much. Does this just apply to .md files or can I use this to preview the API (generated from the XML) as well?

Id also like a tiny bit of clarification on the desired result for the API documentation. Is the desire that the XNA documentation is preferable to the MonoGame API documentation language? Or should I generally only replace MG API documentation if the XNA is clearer/more detailed? Or should I be looking for instances where the XNA API documentation has more information (like detailed descriptions in the form or )?

The MonoGame API documentation in general seems pretty good and largely mimics (in what I presume is a legally distinct way) the XNA API documentation. So I just wanted to check with you to make sure that if I take this on I would be implementing the desired changes. Thanks again!

[BlueElectivire]

@dmars8047 I am unfamiliar with the app mentioned, but most IDEs (visual studio, vscode, i suppose rider as well even though I don't have personal experience with it) will show it to you when you reference the function or class in question (perhaps even when you hover over the declaration, but i dont remember for sure).

[dmars8047]

@BlueElectivire that is very true. And in most cases that will suffice for a preview of the XML comments. However, there are cases in the XNA API documentation where they use photos, links, and other assets. It would be helpful to ensure that those render properly.

For example, the remarks section in this link - https://docs.microsoft.com/en-us/previous-versions/windows/xna/bb195165(v=xnagamestudio.41)

Its not a big deal either way. Just thought I'd ask.