I wonder, if it would be possible for SideFX team to stop working on Houdini for a month, and finally create some useful documentation?

Trying to guess what a node expects and what is the output drives me crazy. The state of documentation is more akin to internal developer remarks, than user-oriented documentation.

One way to judge the abysmal quality of the documentation is to test how badly AIs are able to answer questions. There is almost no tool that is as opaque to AIs as Houdini. For comparison, ask questions about Unity and check the quality of answers.

That said, I still much prefer Houdini to other tools, it's absolutely amazing, and the community is fantastic.

Of course, I could be wrong and just unqualified after only 4 years of work with Houdini.

One way to judge the abysmal quality of the documentation is to test how badly AIs are able to answer questions. There is almost no tool that is as opaque to AIs as Houdini. For comparison, ask questions about Unity and check the quality of answers.

It has very little do with the quality of the documentation. Unity just has so much discussions and resources on the internet. Houdini is not even comparable. If you ask questions about some less used parts of Unity (e.g. Playable) Ai will get it all wrong. AI constantly hallucinates about what USS actually supports because there are even more discussions and resources about CSS and AI conflates them. AI answers' quality is proportional to the popularity of the subject.

Houdini just has practically zero dicussion compared to popular free tools. Unfortunately it's a historically niche software, targeting studios that can afford $10000/year/seat.

I swear 90% of the questions on this forums are answered by like 5 (very kind) individuals. When they retire no hobbyist would be able to pick up Houdini ever.

Another issue is that the most valuable knowledge is hidden inside examples/content libraries. They're usually high quality, but completely invisible to search engines and AI.

Yet another issue is for some reason, Google hates the SideFX official document. It'd rather show me a random unrelated topic on ODForce or this forum than the official document. Perhaps it's because the official documentation site has quite a lot of broken images links and not CDN-ed so Google algorithm punishes it (as Google should). It's also unbelieveably slow to load for a 100% static site. You can type the exact name of a feature, which the document clearly states, and google still can't find it. Try "houdini menu script".

All good points, @raincole.

Still, we (or AI, or whatever) should not rely on forums and user guesswork. The documentation should contain as much information as possible (ideally, all of it).

Example, the first that comes to mind:
Say you want to work with heightfields. The doumentation lists the nodes and their options. Not very useful but at least something.
But the context is entirely lacking (after all I already understand that Heigh refers to the height and Mask to the mask).
What type of data feeds into heigh, what into mask? Which nodes are providing that data? Would it kill the engineers to provide examples? Or at least links to relevant part of the documentation (if it would exist).

Your point on the user community of Unity being larger than Houdini's rings true. But while there are probably more people doing Unity, the quality of knowledge in the Houdini community is amazing. And, let's be frank, SideFX engineers create a much more consistent and stable product. 

That's what I'm trying to suggest - a great product should go with a great documentation. Stop adding features for a month and cleaup the docs!