I realize that this post maybe controversial but I feel that I have to speak up about my most frustrating area of Houdini - the documentation.

SideFX - forget about new features - rewrite your documentation. It’s abysmal. It’s incomplete. It’s in-cohesive. It’s anything but artist friendly.

Just imagine that someone new to Houdini opens the documentation, now go read the ‘chapter’ on modelling and animation.
Then ask yourself a question - would this user really know how to animate or model after reading this ‘thing’?

It feels like either a bunch of mumbo-jumbo of outdated copy-pastes or technical descriptions using a non-humanoid friendly language that that only a PhD scientist might understand. It doesn’t flow. It doesn’t teach. In most cases it feels like it’s an output of some code documentation targeting other programmers vs rather than artists. In most cases it’s outdated. In some cases it’s more confusing to the reader than not reading it at all.

The documentation seems to be an afterthought in Houdini and it shows.

Yes, I realize that there are some great tutorials out there, but with the development cycle this awesome, most of the tutorials older than 2 years are outdated. The techniques are not up-to-date anymore. The UI and attributes have changed (e.g. solvers).

Rethink and rewrite this whole thing.
Start each area with description of fundamental concepts in a humanoid friendly way.
Follow with some cohesive and progressive how to examples.
Describe core nodes and how they could be used together.
Describe parameters in a way that the user would actually understand what they are for and how they might be used.
Then document each nodes from an artist lens. What does this node do. Why is it important. How could it be used. How could it be used with other nodes.

Often when watching tutorials we have a reaction of ‘oh my god, I had no clue you could use this node to accomplish this’. Or ‘oh, so that’s what this parameter actually does’.

Please do something about this. H20 is approaching. You’re targeting non-technical humanoids more and more it seems. Write for them, not for PhD students or programmers.

Cheers.

However the new Karma user guide is great,it's a lot of work,they are working on that.

I agree with both of the above. The new Karma guide is EXCELLENT and should be a template for all future docs and guides. Existing docs going back many, many years are of variable quality and usefulness. Updating all that seems like a nearly impossible task, so I'd be happy to just see more artist-friendly stuff going forward.

I'd say they should ensure every node (at least every SOP) has at least one example. Sometimes it's just impossible to read the documentation and "get" it. You need to look at a working example.

While the docs of Karma, Solaris and KineFX are not bad, I still hope they provide the whole working example examples as well.

BrianHanke
Updating all that seems like a nearly impossible task

it isn't. you just sit down, and update it. sounds possible enough to me

As much as the Docs should be improved in certain areas, I don't really agree with you.
A lot of nodes have load/launch examples literally showing you how to use it.
Houdini is a technical program, doing low level technical things, sure you can wrap up the Docs to include
less technical descriptions, and it would help, but where do you draw the line? Do you include a
default "I'm not technical" desc, then an advanced "I'd actually like to learn the correct underlying Computer Graphics"
desc for things?

They are dry Docs in a lot of places, and in some totally lacking clearer outlines, but I don't think they are as awful as
you are making out. Computer Graphics is a technical field, and Houdini is the most technical tool, with nothing hidden or abstracted
from you, so it's kinda assuming you are coming into it prepared, or at least willing to get into a mindset.

Raincole do you really need an example file for every SOP? So many of them are straight forward literal things.


L

lewis_T
Do you include a default "I'm not technical" desc, then an advanced "I'd actually like to learn the correct underlying Computer Graphics" desc for things?

both; i have a revolutionary concept in mind: you divide the topic into "beginner" and "advanced" sections.

This is another one of those problems that has already been solved, so it's mostly a matter of implementing an existing solution. I like Azure docs a lot. The gold standard for me is if I can go to the docs and come away knowing exactly how to accomplish a task. I find that to be the case 100% of the time with Azure. Houdini... it's a coin flip. Usually it's faster just to ask here or on Discord.

Take this one from Azure: https://docs.microsoft.com/en-us/azure/storage/common/storage-ref-azcopy-copy [docs.microsoft.com]

Very simple description
Technical description
Examples
Complete list of options/parameters

Now apply that format to this one, for example. https://www.sidefx.com/docs/houdini/nodes/sop/guideprocess.html [www.sidefx.com]

Guide Process

Apply transformations to guides/hair, such as frizz, wave, and length.

Advanced

What they have there now

Examples

Small node networks with different options selected and pics of results. (By the way, this is why I said "impossible task" earlier. It would take a thousand years to create all these samples...)

Parameters

Also what they have now

It's amazing that any of us became good at Houdini considering how bad the Docs apparently are.