We started this week to do a major overhaul to the documentation of our tools.
The first step was to use a different HTML generator.
We used GhostDoc before, but we have had some big problems with the generated HTML. Many links were broken because GhostDoc generate links with the wrong case (we reported this to them but so far, no luck with a fix). Although we could fix this by hacking the HTML ourselves, it also meant the documentation was not searchable, which makes it much less useful.
We use Sandcastle now, and so far, it seems to be working great. Sandcastle also allows us to add some conceptual documentation, which means we can bring together the documentation spread all over the site to one place. You can already see the extra pages we added for Grids 2: https://gamelogic.co.za/documentation/grids2/.
The second step is to “translate” the many documentation articles we made for Grids 1 to Grids 2. One example of this is the guide we wrote that shows how to do everything in Amit Patel’s great Hexagonal Grids article with the Grids library. You can see the work-in-progress result here: https://gamelogic.co.za/documentation/grids2/html/f9d4f8f2-6eaa-4e52-bb24-0bca2a06a541.htm.
The third step (and this is really happening concurrently with step 2) is to add the many missing API documentation entries, starting with the most important classes (such as GridPoint2 and IGrid) and working our way down to the more obscure machinery such as IPointPartition.
And after this, we have to do the same for the other tools!
It will be a long process, and we want to upload the newest version of the documentation every day or two, so it means you may see the odd ghost of a GhostDoc tag that is misinterpreted, or pages that are incomplete. Please be patient 🙂 And if you see anything amiss, please let us know, and if you have questions, ask us on the Knowledge Base.
How’s this going?