I wrote a Getting Started Guide!

I created a collection of html articles to help new developers get started with Monogame.

The guide matches the look of the monogame website, so it ‘fits’ into the established Monogame brand.

The guide is built around 3.5 and will be updated when 3.6 releases. It covers a wide range of topics, including properly using the pipeline tool. It also covers basics like adding, drawing, and modifying textures, fonts, and sounds. In addition, it includes an example game with full source code and assets for both desktop OpenGL and DirectX. The example game is called ‘RescueDog’ and was created specifically for this guide, by me.

The game was also translated to japanese, as explained in the Localization article.

The Getting Started Guide is available on GitHub: https://github.com/MrGrak/Monogame-Getting-Started

For now, I’m thinking that the Getting Started button on the Monogame website could just link to that repo. The Guide is built using pure HTML5 and CSS, so it can be integrated into the Monogame website pretty easily. I’m not sure who I would need to contact or who would need to approve this integration.

Finally, I wanted to make it available to everyone so others can contribute articles to it. I hope to improve and expand the guide to include more articles in the future. For example, I’d like to add networking articles explaining lidgren. I’d really like to add an article explaining how to run Monogames on the Xbox One.

I really enjoy developing with Monogame, but I know how hard it can be to get started with it. Tom Spillman mentioned that Monogame could really use some documentation in one of the monogame youtube videos. So thats what prompted me to create this guide.

Please let me know how it can be improved, and feel free to fork/contribute.



This is awesome! If you want to contribute this to the docs, you can open a PR. You know how to do a PR? If Tom thinks this is a good fit for the docs this will be a great boost! The docs are in markdown, so html should work too :slight_smile:

Maybe some edits will need to be made as this is written as a standalone tut. But I can tell you put a lot of effort into this. Thanks! :smiley:

A quick note though. The more general programming pages like those about classes and OOP probably aren’t a great fit for the docs. The aim is to explain the MG API and best practices rather than being a full-blown zero experience tutorial.

Great feedback, I just updated the Guide and removed the class articles.
I’ll learn more about git before I attempt a pull request.
Please let me know your thoughts about any edits you would like to see.

Do you think it would be better to present the articles assuming the user had some C# knowledge?
How much should the articles assume the user knows about game design?
I was considering also creating a ‘Community Cookbook’, or a collection of useful code snippets.
I think more advanced topics could be presented there, rather than the Getting Started Guide.
What are your thoughts on that?

Woah, you can keep them on your GitHub page. There’s people that can definitely benefit from it. But just not all your pages fit in with the MG docs :slight_smile: I think it makes sense to distill it and assume people have some basic C#/programming experience, but link to the full thing in the tutorials section for people that don’t.

I think a repo with useful snippets is really nice. There are probably a bunch of those :stuck_out_tongue: If you put a link in the monogame-awesome GitHub repo people will have an easier time finding it. I think you’re right that these things shouldn’t go in the official docs.

There is a GitHub issue worth reading about the structure of the documentation here https://github.com/MonoGame/MonoGame/issues/2520

Let me know if you need some help with Git or GitHub, it would be great to get some of this in the docs :slight_smile: Since it’s just documentation I think you can even do it all through the GitHub website. Check out the Contributing file under docs in the MG repo. It tells you how to fork -> edit -> PR without having to use Git directly. If you look at the other files there, you’ll see they’re all written in markdown, but like I said markdown generally handles html pretty well. You don’t need any headers/footers and stuff like that. I recommend not making changes (especially not removing) stuff from your original repo :slight_smile:

Pinging @Tom

I think it’s ok to remove articles that don’t fit into the idea of a Getting Started Guide. I’ve still got the articles saved locally on my machine, and I’m thinking that they’re probably better suited for a Beginning Programming Guide that I may construct later on. My primary focus right now is on the Getting Started Guide and laying a foundation that’s easy to maintain, update, and most importantly is user friendly.

You guys have been working with MonoGame for a long time. You’re familiar with github and the docs available there, and to a certain degree you have enough experience that you probably don’t use that documentation much and instead spend most of your time in the develop branch, looking at the source. New users don’t do this. New users need something that’s easy to understand and simple to use. I really think that was part of XNA’s success - there were webpages with easy to understand tutorials to help get people started. MonoGame doesn’t really have that… and I think that’s what I’m trying to create. I’m not trying to add to the already existing MonoGame documentation, I’m trying to ‘reboot’ it and make it more user-friendly and approachable.

I’m attempting to look at this documentation with fresh eyes, so I hope everyone understands that I’m trying to help and improve a framework that I use and enjoy. Having said that, I did a documentation audit and here are my findings.

The image has been scaled improperly by this website, so I’ll briefly summarize it. MonoGame.net provides a series of misleading links that eventually leads to GitHub documentation. For every necessary link required to get to the GitHub documentation, there is a nearby link that provides little to no value. In fact, the Codeplex Documentation link leads right back to Monogame.net. This process is confusing for new users. Links without value need to be removed, and a single link from Monogame.net needs to lead to the github documentation repo, and this link should be the first link that appears on the monogame.net documentation page.

I’ve been working as a UI designer for around 13 years, and in my opinion Monogame’s documentation is difficult to locate, difficult to understand, and requires knowledge of github. This needs to change. I say that because I’m passionate about what Monogame represents, the open source cross platform successor to XNA. I’ve done my research, and I know that the Monogame’s Documentation has been directionless for years. In the issue Jjagg linked to, I can read Tom’s frustration about this in his post from Feb 10, 2015. More than a year later, and nothings changed. No-one wants the responsibility of managing documentation - it’s not fun. But it needs to be done. I think I’ve hit the main targets for what the Getting Started Guide should have in it. But I’m not content with the current state of how documentation is presented to new users. I strongly suggest that a more user friendly approach be adopted, one that simply presents articles and tutorials, with images, in a website format - not in a github repo. This is how and why I designed the Getting Started Guide.

I don’t want to get rid of the docs in the official repo, I want to create an intermediate representation of them that’s more user friendly, that’s integrated into the Monogame.net website. People shouldn’t have to go to github to learn how to use Monogame. People should be able to learn how to use Monogame from the Monogame.net website, using a series of easily understandable tutorials and articles. This is what needs to happen. And you may disagree with me, and that’s fine. But I believe that a lack of action has created the situation that we find the documentation in now - and the only way to change that is by taking action. I’ve put a lot of thought and planning into presenting the ideal solution to this documentation problem, I hope everyone can understand the how and why behind this design.


This is exactly the goal of the MonoGame docs :slightly_smiling:

Oops, we have to get rid of that one :stuck_out_tongue:

The documentation is here on the website under ‘Documentation’ as you’d expect (http://www.monogame.net/documentation/?page=main). The documentation source is in the official GitHub repo. Every night the documentation is rebuilt and changes are published here to the site. The documentation on the GitHub wiki is outdated, but there are still valuable docs in there that should be ported to the official documentation. But if you didn’t notice this is how it’s set up, that means it isn’t obvious enough and needs to be clarified. It’s a bit messy because of the history of the docs, but Tom has set up things nicely right now. Please take a look at the docs here on the site, there are some good pages on there though not nearly enough and some stuff is outdated, but the format is nice and the workflow for adding docs is too (but it takes some getting used to).

This looks fantastic… great job on this.

We can link to it, but we won’t integrate it as is.

Our docs are versioned with the source code and updated with every PR. It is all an automated process driven by a config file and MD pages. The source of our docs lives here along with a guide on how to contribute to them:


Rebooting the content is fine… as long as we keep some of the technical stuff like command line info for the tools and how to package things for Stream and the like. We don’t have a lot there beyond that to begin with anyway.

However the process of how the docs are generated and integrated with the website will not be changed.

I think this is where you got on to the wrong track.

We totally agree… people shouldn’t use GitHub to read about how to use MonoGame. This is explicitly why http://www.monogame.net/documentation/ exists.

For some reason you have mistaken the old legacy docs for the current docs. We’ve left this up because it has some useful info that needs to be transferred into the official docs, but I can see now how people will not read the warning on the first page and get confused by it.

I’m going to look to backup then delete the GitHub wiki docs today.

Difficult to understand… yeah maybe.

But it is as easy as it can be to locate… it is literally the third link on the top of every page of the website. No use of GitHub is necessary.

I don’t disagree with you at all.

The only issue is we have a system in place for documentation being versioned with the source code and being published to the website. If you can adapt your work to that process then I think we can finally improve the docs.

1 Like

Haha, I was just writing on some stuff and was gonna ping you :smiley:

Wow I was thinking about making the same thing this weekend, since the base monogame documentation is so lacking, but then you come along and make it with a much more interesting game concept.

Good job.


So I just killed the old wiki. If anyone ever wants to go thru it again it can be cloned from https://github.com/MonoGame/MonoGame.wiki.git and pulled out of its history.

And put up a PR removing all references of it from the docs and guides

Once this is merged the website docs will also be updated to remove the links to the old Codeplex site and the wiki.

There should be zero confusion as to where the docs are now.


Did we loose you on this @MrGrak ?

I’m still here, watching the gears move. It’s very interesting to see a talented group of developers work, I still have much to learn. I kinda felt I was a bit too forward with my thoughts in my last post, so I’ve been ruminating over everyone’s replies.

That happens… nothing to be worried about.

The next step here would be seeing how we could convert your content to MD format and structure it to fit into our doc system. In theory it should just work… but we can also make to the tool if we run into any issues.

1 Like

This won’t get forgotten, right? That would be a real shame :stuck_out_tongue:

I just remembered another thing that came up recently was the Stack Overflow Documentation system. You can read more about that here:


And here is the current MonoGame documentation topic page:


@MrGrak - If you don’t feel comfortable working within our documentation system then maybe contributing your work to the Stack Overflow Documentation system is another approach to consider.

MrGrak this is great! I wish I could have had it back then when I started my adventure with MG. Even after 2 years of coding in MG I find some of this RescueDog code usefull and this is nice. Aweseome job!

First I’ll say anything I don’t mention I consider excellent. Quite often did I think “wait, that’s not right” when you pointed out that exact issue on the next page :slight_smile: I did have a few niggles, just as I’m free to mention them you’re free to ignore them.

  • Near the end of “Inspecting Game1.cs” you mention MonoGame runs at 60fps. To clarify, it targets/limits 60fps by default, this value can be changed.
  • The Arial font is actually copyright. I’ve never seen anyone care much, but why not get licenses right - https://en.wikipedia.org/wiki/Arial#Free_alternatives - the actual ‘glyphs’ aren’t copyright so alternatives can be made 1:1 pixel perfect.
  • When I hear ‘game state’ I immediately think of a Finite-state machine. I find it hard to identify with the “What is Game State?” paragraph in “Managing Game State”. I’m having trouble giving a better explanation but simply adding a short mention of ‘encapsulation’ should clarify things, explaining that Game States are completely separate (even if one may be displayed over another). Or maybe I’m way off-mark.

Special mentions for the Optimization and Localization pages. Too often do these get left out. Kudos for the points where you clarify an optimal solution, with the beginnings of how to go about implementing it, and clarifying you’re using a simple solution along with reasons it’s not optimal.

You’ve left me wanting more which is the mark of a good beginner’s tutorial. :thumbsup:

1 Like

For anyone interested in this guide, you can see the HTML content without cloning/downloading the repo by visiting the following link http://rawgit.com/MrGrak/Monogame-Getting-Started/master/index.html

Why isn’t there a github.io page created for it?

For few of you who don’t know, github.io pages are automated web pages generated from github repos with specific name, example: https://github.com/FNA-XNA/fna-xna.github.io has https://fna-xna.github.io/

For more info on how to set it up look at: https://pages.github.com/