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.
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.
