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.ā
The only reason I have a GH account is because it was the only thing that worked to get me on this forumā¦ otherwise I was purposefully avoiding itā¦
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
Sorry for the confusion Currently the docs are still using the old doc generation system. Iām pushing to switch to docfx instead, but for now things have not changed. Docfx uses markdown, just like the current system, so things wonāt change as to how to contribute anyway.
So to edit the docs, you still:
Fork MonoGame
Edit documentation pages in your fork (which you can do by navigating to the relevant docs page on GitHub in your fork in the browser and clicking the edit button)
Set up a pull request to merge your changes into the MonoGame repo
Iāll post an in-depth guide with images once I have some spare time
There are āImprove this Docā links on most pages, but you should not use those yet, since they link to the doc pages on my fork of MG instead of the actual doc pages (I can probably make them link to the official MG repo, will look into it).
The idea is that those pages are embedded in the docs on this website. Will look something like this:
Is this the set of documentation that we can work with using DocFx?
I have used quite a few source-control systems and currently have a version of Subversion set up on my own server. However, I have never had the opportunity of working with a document system outside of SharePoint, which I did some development for a number of years ago.
Any guide or information you can provide me with will be greatly appreciatedā¦
Docfx doesnāt handle sharing the docs. I used Git for that.
Docfx generates HTML pages from markdown files and table of content (toc) files that specify the structure. The toc files are similar to the config.xml file used by SharpDoc.
As a preprocessor step, it can extract the public API given .csproj files and source files and turn it into markdown and toc files (that will in turn be used to generate the HTML for the final web pages).
To actually host these pages somewhere, you need to get the files generated by docfx on your server. Hereās how I did it for the MG docs:
let docfx generate the HTML pages in the _site folder. This folder is not added to the MG repo (I added _* to the .gitignore file). We donāt have to have it in source control because it is all generated from files that are in version control.
The _site folder now contains the HTML, css and JavaScript files that make up the entire website. In the root of that folder thereās an index.html file that is the landing page of the website.
To set up GitHub pages, all you need is a repo with the HTML/CSS/JS files and an index.html file in the project root for the landing page.
The next step is quite obvious. I Initialized a Git repo in the _site folder and pushed it to a new repo I created on GitHub. Then I enabled GitHub pages. Thatās all there is to it.
