WiX documentation consolidation

The repo for the docs.firegiant.com site lives at https://github.com/firegiant/docs. It’s built with Astro, which Rob assures me is filled with shiny Web goodness and some other things he mentioned but I’d already tuned out after hearing about Web stuff. It’s way faster to build than the old wixtoolset.org site, which is great when iterating on doc.

If we’ve done our jobs well, all wixtoolset.org URLs will redirect to the new page at docs.firegiant.com. If you find any missing redirects, please file a bug.

Rational documentation rationale

So why did we consolidate docs? The short answer is that without significant external contributions to the WiX documentation, it falls on us—mostly Rob and me as maintainers with support from FireGiant over the years—to create new documentation, fix errors in existing documentation, and figuring out and filling the areas that have missing or not enough documentation. That’s a big undertaking so streamlining the processes and consolidating on one site with one Web build framework simplifies our work.

And it is, for better or worse, our work. Back in the halcyon days of 2009 when WiX v3 was released, we had blogs, wikis, and plain ol’ contributions from many different users. That was also right around the time Stack Overflow was born and grew quickly in popularity. All told, it meant that with your favorite search engine, you could find information on all kinds of WiX-related topics. While some of those sources have gone to the big bitbucket in the ether, most are still available.

Back in 2013, we made the choice to keep WiX v3 “100 percent backward compatibility of authoring and libraries”. That meant that all the documentation you might find on WiX was also backward compatible.

When WiX v4 (eventually) came out, it broke backward compatibility. (We had good intentions, really. Remember that WiX v3 came out in 2009, so we had years of thought about how to make the language better. You might have noticed that we’ve maintained backward compatibility since then, choosing to add new and better ways of doing things instead of removing and replacing. We learn our lessons.) A lack of backward compatibility meant that a lot of available doc appears to not apply to WiX v4 and v5.

Generally, the WiX v4 language is highly compatible with the WiX v3 language. But certain changes, like conditional expressions moving to attributes and major reorganizations like in the Package and Product elements, make copying and pasting from Stack Overflow or an old blog post less likely to work without a bit of human intervention.

The lack of WiX v4 and v5-specific doc is reflected in increased complaints and discussion forum posts requesting help. As I said last meeting:

So it falls to us and, because some people are blaming FireGiant for the lack of doc, FireGiant is taking on some of that doc challenge.

As part of this consolidation, FireGiant is sponsoring additional effort to add new documentation and improve existing documentation. So, for example, should the muse strike me, I’ll be able to add even more of my definitely-free-of-typos and elucidating prose to the site.

This work won’t appear immediately or quickly in its entirety. On the contrary, documentation is always an ongoing effort. And now it’s on our plates.