Help Us Improve MonoGame Documentation!

About a week ago in another thread @Tom mentioned that he was hoping for more people to dive in and start writing some MonoGame documentation.

I think this idea is great and I’m sure there are others out there willing to contribute. However, it’s not clear how we edit the documentation. If someone could enlighten us on this, that would be fantastic.

Here’s a little blurb I wrote the other day…

We need help writing the MonoGame documentation!
As you know, documentation is what separates good open source projects from forgotten ones and as it stands the MonoGame documentation is only a little way to being great. If we all band together, we can make it great!

This is call out to all MonoGame developers willing to help if you have tutorials, code snippets, experience with the various platforms, youtube videos or any other form of documentation. Let’s gather it all together in one place and make MonoGame even better.

http://www.monogame.net/documentation/?page=main1

Followed by instructions on how to contribute…

3 Likes

I’ve written a new TexturePacker/MonoGame integration tutorial blog post (see other thread). I see there is a tutorial section in the MonoGame documentation that contains a link to my Spine tutorial which is cool. I’m happy to add my new blog post to this page as well, however I’m guessing that it isn’t editable by everyone (i.e. not a wiki) so I’m guessing someone else will need to add the link.

1 Like

It would be nice if it was. Just sayin’

The docs are editable by everyone. Check out the README.md file here:

https://github.com/mono/MonoGame/tree/develop/Documentation

Since it works via GitHub it allows us to officially review all docs before submission and lets us version the docs along with the code changes.

So for example the tutorials page is here:

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

You can edit it right from the GitHub UI in your own fork and get a pretty WYSIWYG experience.

3 Likes

This information should probably be on the first page of the documentation.

I tried doing it myself but got a 404 error from github. Probably because I already have a MonoGame fork in my account that was forked from DDReaper’s Portable version.

I’ll try again later.

Putting a notice and link into the first page of the docs to the GitHub docs README.md would be great.

I can’t tell if this is sarcasm or not?

Of course I was not being sarcastic.

It would be great to put a link on how to help contribute to the docs on the first page. Something to add to the existing “WORK IN PROGRESS” blurb I already have there.

Sorry. I was just a bit confused by your sentence.

I’ve updated the welcome.md page and created a pull request.

Do you guys accept video tutorials?

We would love to see them, but we have to work out exactly how we would include them into the docs.

First it makes sense for the videos to just be put up on YouTube. No reason to do anything fancier than that. We can then easily include it into the current MonoGame channel in either the “Tutorial Series” or “Learn MonoGame” playlists.

Once we have it there we can consider adding a link and/or embedding select tutorials within the docs. We should probably just make these part of the regular documentation and not just have a list of video tutorials or anything. This would suggest these videos should be short and on one particular subject.

Other thoughts?

So another small project idea.

We should take the time to go thru the old GitHub wiki…

https://github.com/mono/MonoGame/wiki

And figure out what is good and can be translated to the new docs.

After this is done we can delete the Wiki and redirect everyone to the website docs.

Yes,I agree with you,after i finish my game lib i`ll start preparing for making good quality vids!

So we’ll have to start supporting versioning in the docs.

  • Documentation for latest stable release.
  • Optional documentation for previous stable releases.
  • Documentation for current develop branch.

The question is how should this work?

When you go to…

http://www.monogame.net/documentation/

… what should you see? Do you see the latest stable release docs? Do you see a landing page with links to the various doc versions?

Or should we do it like MSDN does…

http://msdn.microsoft.com/en-us/library/microsoft.xna.framework.vector2.aspx

Where there is a drop down for “Other Versions”? It is more complex to setup and maintain, but is it more useful?

How should the URLs for different versions of the docs look? Like this…

http://www.monogame.net/documentation/3.2/?page=Getting_Started
http://www.monogame.net/documentation/3.3/?page=Getting_Started
http://www.monogame.net/documentation/develop/?page=Getting_Started

Thoughts?

Bump! This discussion has gone dry!

I like the MSDN style.

I really like the MSDN style as it provides the ability to bookmark a specific piece of documentation but it’s a living record, it changes as the platform is revved. That said, having the ability to select a version as well as platform would be really nice, will probably take a lot of work taking platform specific documentation, maybe keeping it in a section that is in-line but collapsed by default would be a better way.

Is it that this is hard to do in the current CMS or you’re just not sure how you’ll setup the tooling for this yet?