Help Us Improve B&R Documentation - We Want Your Honest Feedback! 📚

[Andy_Walker]

Which documentation resources do you use most often? (Automation Help, user’s manuals, Downloads section, etc.)

Automation Studio Help primarily. I prefer the old-school Help application rather than the online help. I don’t really have a good reason why - perhaps it’s just what I’m used to, perhaps I have too many tabs open in my browser and I find I lose the Help tab Also, sometimes the links in the online help are broken.

I use the online help more for APROL, because it’s available without having to log into my engineering server, but it’s not a great experience - see below.

How easy (or difficult) is it to find what you need?

Automation Studio Help:

It’s usually pretty easy. The search is okay, although fuzzy search would be a nice improvement.

One exception is the documentation for the unit test framework, which only appears when you install the unit test technology package - which isn’t great when you’re trying to figure out how to enable unit tests! Similarly for Mapp services in AS6.

Another thing that could be improved is that the documentation for I/O modules only references the modules’ registers - not their graphical configuration pages within Automation Studio. These normally map up relatively well but that’s not always the case - the most recent issue being the osc trace function on an X20AI4632, where the config pages have some options which don’t map cleanly to registers and thus have no help available.

Generally though, Automation Help is great. We’ve only had to contact Support once in the last four years due to not being able to find info in the Help file.

APROL documentation:

It’s really difficult to find anything in the APROL documentation. The search isn’t great, info is scattered over multiple manual pages, and errors don’t tend to come with an error number and pasting them into search doesn’t usually find anything relevant. Quite often, I have tried to search for info in the manual and not found it, only to stumble across it later by accident while looking for something else.

Some things are entirely missing - for instance, the documentation on the EventDriver has a lot of low level information on how it works, but no info on how to actually set a variable to use the EventDriver within APROL.

Other things are in non-obvious places. For instance, when trying to figure out how many bytes a certain type took up, I found that typing in ‘variable types’ or ‘pv types’ into APROL Help doesn’t come up with anything useful. It was a year and a half later that I realised that the Help menu in CAE Manager has an additional entry for the table of PV types!

The manual links in the help.br-automation.com version of the documentation are also often broken - they either lead nowhere, or they lead to a German version of the page.

How would you rate the usability of our Downloads section?

It’s pretty good. I was going to write that it needed to be faster for full text search, but I see that has been fixed! Good work.

Any features or improvements you’d love to see?

In the help.br-automation.com help browser and search results, middle clicking or ctrl-clicking a link should open it in a new window. Neither of these work on search result pages. On actual help pages, middle clicking works but ctrl-clicking doesn’t.

As mentioned above, I’d like to see Automation Studio Help cover individual settings within modules’ graphical config pages.

It might be handy to have a bit of documentation for both Automation Studio and APROL that explains how the C code is preprocessed and where to find the preprocessed output. I’ve occasionally used this to untangle cryptic compiler errors which didn’t make any sense given the code I’d written.

APROL documentation should follow the example of Automation Studio Help - every error should have an error number which leads to more information about that error and, if applicable, troubleshooting steps.

What works really well that we should definitely keep doing?

Bundling the data sheets for every hardware module into Automation Studio Help makes it a large and slow install, but it’s incredibly useful when you need to quickly look up the capability of a particular module - no need for internet connectivity or to download anything.

The code examples for various Automation Studio libraries are invaluable.

Bonus question: If you could wave a magic wand and change ONE thing about our documentation, what would it be?