Why is better documentation something that is rejected?

[BryanCrotaz]

I've made a number of PRs to improve the documentation based on what I've painfully learned over 2.5 weeks trying to get a simple app to install.

For example I lost a long day trying to work out why my wix build worked on my machine, but not on my build server. Turns out that $(SolutionDir) isn't available on the build server, but works on my dev machine when building a single project.

I tried to document this:
wixtoolset/web#242

But I'm told that the documentation already says that. Well no, it doesn't, which is why my PR was created. How, as a user, do I help to improve the docs if the people running the project don't want them improved? Serious question - how - what's the process, how do I help the poor newbie behind me?

When I google the questions I have, I find posts going back to 2009, all saying how badly documented this project is, and the project owners saying "no, it's not, we (as unimpeachable experts in the field) understand it, why can't you" - the reason it, we haven't spent 25 years living and breathing installers, we just need them to work. We need 1% of the functionality. We're not building Microsoft Office, we're building a 10,000 line app with a single feature, that just needs a one form installer.

I'm happy to document the lessons I've learned, if someone will accept that that information is needed. If it would have helped me, it will help someone else.

[barnson]

all saying how badly documented this project is, and the project owners saying "no, it's not, we (as unimpeachable experts in the field) understand it, why can't you"

I'll go ahead and assert that that never happened. But "unimpeachable experts" can indeed make judgment calls on whether a particular edit makes a document better or worse.

how do I help the poor newbie behind me?

Publish all the docs and notes you want on your own site. Self-answer questions on Stack Overflow.

[BryanCrotaz]

But people googling don't end up on a website about large digital signs, they end up on the Wix documentation site. I want to contribute to an open source project and improve it. Sort of the whole point of open source!

[BryanCrotaz]

Going back to my PR wixtoolset/web#242

The comment from @robmen is that the documentation is already present. Where? I couldn't find it. What's the URL?

The best place to have this discussion would be in the PR, but as it's been locked, I can't even ask the above inline with my change request.

[robmen]

That's very strange. The diff I saw only added this part:

but not if you build an individual project in the solution.

Which is redundant with the rest of the line. The way GitHub rendered it failed to take into account the previous commit, which is much better.

I'll re-open the PR.