Thursday, May 25, 2017
If you haven't noticed by now, we've completely revamped the Figaro website using our favorite static website generator. More importantly, we've taken down our Sandcastle-built documentation website and replaced it with an updated version built using DocFX. The repository for the documentation can be found on our GitHub account at https://github.com/bdbxml/help-bdbxml-net.
The documentation website rebuild was no small feat, and it's safe to say it's not really in its final form. While it's a big upgrade from the Sandcastle tools (and that god-awful MAML format Microsoft came up with) the DocFX tools leave room for much improvement in many ways. It works great for what it does - taking Markdown documents and generating websites with it - but if you look at the static website/documentation generation tools of late, many things are still missing.
For starters, one striking feature about the mass migration to JSON-driven development is the simple fact that, because you pretty much eschew formal data structures in anything you build, the common denominator is that everything becomes completely vague in a JSON file. In other words, you have to pay close attention to the what the documentation says when it comes to configuration and setup - even worse, you have to hope & pray that the documentation you're relying on is up to date with the latest developer changes. And in just about every JSON-driven development experience out there, the documentation is badly lagging - leaving you, the developer, in the lurch.
Static website generators are great - we love them, and we're committed to using them for now. But the tooling in most of them is badly lagging. We still think that an XQuery/XML driven experience is a superior approach to many things, especially technical documentation, but sadly, we were hard-pressed to find anything that met our needs in that department at the time of this writing. You can rest assured, however, that when that time changes - and we hope it happens soon - we'll be making another migration of our content to a new, (and what we consider would be a) better, content-driven platform.