When will you fix the broken documentation?

[reduxdj]

The documentation is really suffering, especially since it's outdated and incorrect, a few hours of planned work turns into a true churn with at least 20 hours logged on adding a simple UI to my Wix Installer and custom action since the schemas and examples are so poorly maintained.

[bevanweiss]

If you're either funding it, or doing it yourself, then it might happen.
Demanding other people to do something (for free) to make your life easier just seems selfish... don't you think?

[Korzhukov]

FireGiant makes money on paid support. They are simply interested in poor documentation. FireGiant is not not-profit organization, they are making money on wix, but poor documentation is their business model. Nobody will ever fix it.

[bevanweiss]

If you write the documentation, I'm sure it would be accepted.
Rob & Bob already 'donate' large amounts of their time to supporting open source WiX.

I don't see why FireGiant should have to be a non-profit organization. What difference does that make?
Microsoft aren't a non-profit, nor are Oracle, nor RedHat, nor Canonical (Ubuntu).

FireGiant makes money developing software (generally in the installation space as I understand).
I suspect you also make a living developing software. Should we express disdain for you not releasing all of your work as open source?

[Korzhukov]

I'm not saying they should be non-profit. I don't think they should. I'm just saying that they don't make and support Wix "for free" as you say. Yes, the product is free, but Firegiant are making some money from it. And you (and they too) are using "free software" as an argument to accuse everyone of being selfish, rather than admitting that it's just a business model.

[bevanweiss]

I doubt it's "a business model" for them, since there is documentation, and not just legacy documentation, but stuff that has taken up their time recently.
I don't know of many software engineers (or engineers in general) that like doing documentation. So if doing something for enjoyment, it's unlikely to be documentation.
And hence where an open source project is almost entirely about doing something for enjoyment, then it's not unexpected that documentation will not be 100%.

If you discover something that someone is offering for free, and rather than contribute to it, all you do is demand that the people currently giving it away for free, do MORE of that, and specifically demanding that they do the thing that makes YOUR life easy, without any regard to theirs... absolutely, I consider this selfish.
None of the people that are demanding 'better documentation' have contributed anything to WiX, and yet they are clearly using (or at least attempting to use) it for THEIR OWN gain elsewhere.

So it's a pretty simple situation. If you feel that the documentation is lacking. Then it should be on you to improve it.
That is the core of how open source works. That's why it's open. If there is something missing for you, you can contribute it, maybe it will benefit others as well.
But again, because it's open and free, there is ZERO obligation from others to deliver the things that you want.

[robmen]

Since the very beginning of the WiX Toolset, I've focused my volunteer time on improving the project's code. My rationale was (and still is) that improving the code, especially moving big new features forward, requires a deep knowledge of the intricacies of WiX, MSI, and software installation. Very few focus their career on software installation, so it is logical I'd be one to stay close to the code.

I do appreciate the point of view that if something is not documented, it does not exist. For years, I thought developers might write down what they learn and enhance the common knowledge base. Some did. Very few. Almost none contributed directly to the project. So knowledge is spread about the Internet.

In the end, given the lack of engagement from the community (as exemplified by this discussion and issues like #8183 and #5854), we at FireGiant have decided to take a more active role in the documentation. Those changes should be visible over the next 6+ months, if all goes to plan (and as @barnson is often quick to point out, nothing goes to plan 😄).

PS: The WiX Toolset is an Open Source Project, not a Product. The Project is offered "AS IS". Products (generally) offer more guarantees because you (generally) pay for them. With the success of Open Source, I think our industry has lost track of that distinction. I've been thinking about this a lot lately.

[robmen]

@reduxdj, which exact documentation did you find out of date? I'm especially interested in the parts of the schema and which examples you found were poorly maintained, especially compared to WiX v3.