I found two other options you may want to consider. Both of these options are Content Management Systems (CMS) and may have what everyone is looking for.
The first option is MojoPortal, all of which is completely open source and free. This software is written in C# and ASP.NET WebForms (my preference). The link for this software is the following… MojoPortal CMS.
The second option is DNN or DotNetNuke, also a CMS. The base platform or Community Edition for DNN is free and so are many of its extensions. It is written in C# and ASP.NET MVC. The link for DNN is the following… DNN
The extension, which will be needed for our requirements would be the Live Knowledgebase, which can be found at the following link… Live Knowledgebase
I did some research yesterday on Mojo Portal by downloading the source code and compiling the project. I already knew what to expect since I had tinkered with it a few years ago but had hoped that this group would have cleaned up their act since their software appears so promising.
Well that didn’t work out…
Compiling the source code produced a lot off errors. However, before I could do that I had to install the .NET Framework 4.6.2 for m y development environment. If you don’t use the correct developer package for Visual Studio you can easily kiss your entire development environment goodbye. I had this experience last year and it was not a pleasant one to repair…
Once successfully completed I compiled the entire solution, which consisted of around 12 different projects, which generated the errors I just mentioned. True to form, the people at Mojo Portal implemented a serious of sloppy “gotchas” that produced all these issues by mixing C# 7 with C# 6, which is what I use with Visual Studio 2015.
It took me a while to find the solution, which should have been up in big, red, capital letters in their FAQs but the resolution was buried in a thread on their forums.
To compile Mojo Portal cleanly I would have to use a hack to upgrade my C# 6 to version 7, something which was not recommended so I did not do it.
Unfortunately, this is the state if the majority of Open Source projects today, which unfortunately is also reflected with MonoGame. It is seemingly never the product but the lack of quality documentation, which is what started this thread in the first place…
I thought you were making your complaints about the interface in general as it regards a Wiki, not the implementation of an Open Source project…
In any event, I had been hoping that by now, Mojo Portal would have cleaned up their act but they apparently didn’t.
DNN is the only CMS I have ever had any success with since it was quite straightforward to install but they are going towards a commercial distribution of their product and as a result their site has become somewhat confusing as to what is currently free and what isn’t.
I’ve been using Monogame for two years now and I absolutely love it. (This seems a good opportunity to say a big thank-you to the developers - and I hope to have something of interest to show you around Christmas).
I certainly would have appreciated access to an easy-to-read Wiki while I was learning the ropes. Something that gave me a feel for the range of MG’s capabilities, examples of good strategies for handling common tasks and links to more detailed advice.
Once you decide your format, I’m happy to volunteer a couple of days trawling through the forum to build up some material.
I have done further research on the use of Open Source tools to create a documentation site. The last one I tested was a Wiki still in popular use, Screw Turn Wiki. However, like the previous tools I have tinkered with, this too had compile issues.
As a software engineer, my standard when using such software has always been that if it doesn’t work correctly right out of the box, it is not worth your time trying to figure out the issues.
I know it has been suggested that we use the current documentation page within the MonoGame web site. However, doing so does not provide any guide as to how we may want to design the presentation of a full site to support good documentation for MonoGame.
For example, we would want to set up the following sections at the very least…
Basic Tutorials
Advanced Tutorials
FAQ by Category
Third Party Articles
Third Party Sites
Code Snippet Repository (compressed in zip-file format)
Project Repository (for those who want to contribute their projects / compressed in zip-file format)
This is tall order but one I believe can encompass everything people would require to do their research in a single place.
Since, the MonoGame Documentation Page has been rather poorly maintained, if we can get this up and running, the developers at MonoGame may want to consider simply putting a “redirect” on their documentation page to this new site, which the entire community could then easily support.
Though I had been hoping that we could use Open Source software to quickly develop a basic system, it does not appear with what is available that this will be feasible. As a result, maybe we should consider the following factors for those who may be interested in pursuing such an endeavor.
We write our own Wiki-like system from scratch using ASP.NET WebForms (which is much faster to develop with and just as powerful as the MVC option).
Visual Studio Community Edition is an extremely powerful IDE (the latest is VS 2017, though I still prefer using VS 2015). VS Community Edition provides just about all the features of the Professional Edition for which I had a professional MSDN subscription license for many years; so I know the differences.
If we require a third-party suite of tools, Syncfusion also has a Community Edition which provides the entire line of all its platform tools absolutely free to developers. They are as good as any other tool suite so if needed, we can take advantage of it.
For a database I recommend either SQL Server or MySQL since both are commonly supported on hosting sites (I recommend WinHost for their excellent services and developer friendly infrastructure.).
To begin with, I have been researching database designs that could support such a project. It will provide enough information to get an idea as to how we should proceed with an interface…
You’re just moving the issue elsewhere. MG’s docs are easy to contribute to by anyone with a GitHub account and a web browser as stated in this document, but people don’t. I don’t see the benefit of hosting this documentation on another website and I don’t understand why you think it would be easier to maintain on a seperate website or why people would somehow be more inclined to contribute. Like you say, the official docs are poorly maintained. Why not just fix that and encourage other people to help out instead of starting a new documentation website that supposedly would be properly maintained and have the poor official docs link to it?
Everything needed to handle documentation like this is in place on this website, the only thing you need to contribute is a GitHub account. The official MG docs on this website use open source software and are automatically updated when a pull request modifies it. They allow to organise pages in a simple and intuitive hierarchical structure and have a consistent theme with the colors of MG.
There are a lot of third-party resources for XNA and MG and I think the effort of setting up another website with a wiki and all that’s suggested here, would just add to that list.
Please explain to me what you mean by this, because I do not understand the argument.
I’d love to hear some solid arguments for setting up a seperate website, because I really don’t see the point. Just to summarize, the arguments for adding to the docs here:
Easy to find. This place is where people will look and we don’t have to redirect them.
People know it’s official.
Makes MG looks more professional.
Anyone can contribute through a pull request without leaving the GitHub website, and all changes can be checked and commented on by anyone.
There’s a great pipeline for publishing the docs. Everything is automated. If a PR is merged the docs will be updated (I think daily, but might be immediate, I’m not sure).
Markdown syntax is fully supported for easy formatting and nice looking pages.
There’s an intuitive hierarchical doc structure.
Everything is set up already, there’s no extra work to do at all.
The doc system is very easy to understand, there’s no investment needed to learn how to contribute except maybe for getting to now Markdown syntax (which is very simple to pick up).
If anyone can think of downsides to this current approach, please state them so we can discuss ways to work around them.
Alternatively, once you’ve signed up you can use the “Create new file” and pencil (“Fork this project and edit this file”) to have github do the forking work for you. All you do at that point is create a pull-request and your changes get gathered up into the pull-request.
You can get by with the web-based tools when you’re making basic edits. But any structural changes (new pages, etc) should be done properly with a fork checked out on your machine and then sync’ed back to your fork on github.com. (It might be viable through the web interface, but I don’t trust web-apps to show text, let alone change it)
ALWAYS fill out the commit message box, it’s the nice thing to do.
If it’s initially daunting you can always post your copy-text and ask someone to do the work and link the pull-request so you can see how it all happens.
It’s really just 2 basic steps removed from working with a Wiki and includes a mandatory review (the acceptance of the pull-request).
Using the existing documentation in github for this sort of thing guarantees that your material will have eyes looking at it and if it’s wrong/inaccurate it’ll be much more likely to get caught.
It should also help to prevent it from turning into a rewrite of the GL extension documents mess or such, as more knowledgeable eyes means more “no, that’s how things are everywhere, link these references here.”
I think you might be confusing Git and GitHub. Or is it the actual web interface that you dislike?
For the purposes of adding to the documentation, the steps outlined by @AcidFaucent above let you bypass all of Git’s intricacies.
Please motivate your hatred, because I’m fairly confident it’s founded on misconceptions. I think it’s very hard to set up a custom website that gives us tools and mechanisms as good as GitHub’s.
To get this going I think we should open an issue on GitHub first, so this discussion is in the most relevant place and can be seen and commented on by the maintainers. We can discuss the basic structure and someone can set up a pull request to set it up. After that anyone can send pull requests with whatever they think should be in the docs. I think we’ll figure out guidelines for what fits and does not fit along the way, increasing efficiency as we go.
I’ll admit that I hate Git. So much so that I’ve feigned blind-rage and nuked entire projects / forks / PRs rather than deal with Git (or MingW sometimes, MingW is bile). Even the really cool ones, and I’ve made some pretty awesome things over the years.
My dislike of Git doesn’t change that MonoGame’s existing documentation which is on Github is the right place for the information in question, especially given the relative sparsity of genuine MonoGame related gotchas (I’d suspect that easily at least 90% of all gotcha’s have nothing to do with MonoGame beyond happened while using MonoGame).
There’s even the MonoGame FAQ which is exactly where warnings about the reach profile belongs.
In addition to the MGCB page and the Pipeline Tool page there really should be a page talking about the different files that are handled and such, for all of those “Color” vs “Compressed” etc consequences that are mostly undocumented.
I am not sure why people are complaining about Git or GitHub. Git It is just a version control system and all of them work basically in the same manner, while GitHub is a web-based interface to it for remote collaboration processes.
Seems to me that if we can modify the documentation page(s) to promote better in-depth documentation, this would be the easiest way to go and as Jjagg has stated would provide for a maintenance of a uniform experience for MonoGame developers.
I only made my own suggestions as I always thought the MonoGame site was completely privately controlled and we wouldn’t have access to the formats that may be required.
Besides, my suggestions would entail a lot of work taking away from the primary goal of this endeavor.
@SNaidamast You misunderstood. You do not need to fork the project and let people modify your fork. Anyone that wants to add/modify docs should fork MG and modify their own fork. Then they can set up a pull request to allow MG maintainers to accept the changes into the main project. Send me a PM if you have any questions regarding the workflow
I’ve ported the MG docs to use docfx as the documentation generator in response to this thread. It has some cool features and is way more popular than SharpDoc, so should be more stable too. The website looks a lot nicer and has “Improve this doc” links on every page to make contributing more accessible. The config syntax is also easier than SharpDoc’s. I’ll post back updates here
