• Home
  • Blog
  • Website, Blog and Documentation updates

Website, Blog and Documentation updates

Thursday, May 25, 2017

Where everything gets a badly-needed static website refresh. But we're not completely satisified with the tooling.

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.