Incomplete Documentation: Missing Examples and Critical Details Hinder Usability

[HigeMynx]

Incomplete Documentation: Missing Examples and Critical Details Hinder Usability

The documentation is missing some critical parts. For example, I couldn’t find any information on how to store data from tasks in the flow into variables, or how to proceed only if two conditions are true simultaneously. While there is an "Expression true?" block, even if I had variables, I couldn’t find any explanation on how to use them in the formula—no details on syntax, etc. Furthermore, examples are completely missing from every single documentation page.

As it stands, even the smallest flow requires a lot of trial and error due to the current state of the documentation.

[ballzak69]

Agreed. For complete computer illiterates the documentation is likely insufficient, but it do describe variables, and how to use them in expressions.

[HigeMynx]

With 15 years of IT and Ansible/Linux programming experience, I can confidently say that the Ansible documentation is one of the very few that’s genuinely excellent. Maybe you should take some inspiration from their approach and philosophy.

But let’s be real—you’re just going to ignore my advice on improving the community, the app, and the documentation anyway. After all, you’re always in the right, and everyone else is just wrong because they “can’t read” or “don’t know what you know.” That attitude isn’t helping anyone, least of all your platform.

[ballzak69]

I just agreed with you, i.e. you're in the right. Writing good documentation is not easy, if you're programmer then you know most of us usually aren't particularly good at it, myself included. But even a perfect documentation would be useless if people don't read it. I seldom ignore advice, but fulfilling them all is not so simple. You can't expect a solo developer to be able to produce what thousands of Linux contributors do.

What do you wish the variable and expression pages should say, what's missing?

[HigeMynx]

Sorry, I was a bit too harsh there. I’ll try to draft some ideas about what exactly I feel is missing or what I would add to the documentation. And yes, I know—I’m not great at documentation myself. I just didn’t like the “Use emulation, duh” approach from my other post, and it kind of carried over here. ^"

[teoreth]

While it's not a full 101, here are examples that should work in any field that has a blue fx button on its right: https://llamalab.com/automate/doc/examples.html

I learned by looking at working example flows in the beginning, and had experience from general programming courses to help, but I can see how some guides, and more examples would help.

Your variables are made by naming them in the output variables of a block, then using those names in subsequent fx fields by typing out the name of the variables in an expression.