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

[SyntaxError (Michael Schroeder)]

@kovarj

You’re absolutely right!

Thanks everyone for the great input and open discussion!

I really appreciate all the honest feedback and concrete examples – this turned into exactly the kind of conversation we were hoping for.

To quickly summarize the main points that came up most often:

• Search is still the biggest pain point. Once you know where to look, things usually work – but getting there isn’t always easy.

• AI came up repeatedly, especially as something people already use today to find answers faster. The wish is clear: one place to ask a question and be pointed to the right B&R resources, wherever they live.

• Online documentation is a big step forward and clearly appreciated – especially for accessibility and always having the latest version.

• More context and examples are needed, particularly for newer users. Overviews, background, and “which approach should I use?” guidance would help a lot

• The Downloads section still causes friction, especially when it comes to navigation and version availability.

Overall, there’s a lot that already works well – and very clear signals about where improvements would have the biggest impact, especially around findability and guidance. We will take all of these ideas into consideration as we continue to work to improve our documentation tools and resources.

Thanks again to everyone who contributed for their valuable insights and feedback!

[kovarj (Jaroslav Kovar)]

thanks for summary and thanks for using community for your survey.

[Matt_Buck]

I’ve been using the B&R help since 2006. There have been improvements in that time, but they have been slow.

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

• I try to use the help most of the time, but certain information (e.g. device keys) are not available in the help. I would like to see the help be able to be a local cache of all the B&R body of knowledge.

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

• I understand the minimum character search requirements of 3 characters but there are also 2 character function block names. These limited examples should be exemptions to the search sanitization so that if I type TP, GE, NE into the search it knows to reference the correct function block pages. Having to remember which library they are in and then manually navigate to it is unpleasent.

How would you rate the usability of our Downloads section?

• It has definitely improved over time.
• A cool magic wand feature would be able to download from or reference a third party location for installation files. A company could have a local file share/one drive/sharepoint location where all the updates their employees could need could be stored. The employees could then weekly/monthly just update from the team location. Or even Automation Studio could do a background check while running. Having each employee have to install 1 GB of updates when they urgently need to open a colleagues program.
• All information in the downloads being in the help (e.g. device key info).

Any features or improvements you’d love to see?

• The local/offline selection should be a checkmark in the help menu, i.e. use local, like you can select the tool bars in the view menu.
• Easy exportation into a project specific help, i.e. I would love the ability for the help to easily create a project specific reference help with all of the data sheets for the hardware into a pdf/chm.

What works really well that we should definitely keep doing?

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

• A local/offline nature which is really just a checkout or pull of the online information. All the contents of the help should be a repository based so that updates can be done in a branching nature and done with push (local updates from opening projects with new hardware) or pull (from the website when a hardware or library is added nature). The menu structure should be able to adjust to opening online vs local contents based on what a user has checked out.
  • Example: A base automation studio install contains the minimal sections of the help needed for operation of brand new installation of automation studio (Getting started, standard libraries, etc). If the user adds a new piece of hardware or opens a project, the needed documentation should then be cached/checked out/pushed into the local repo. (Revision of hardware should be different branches of the same header).
  • Don’t know about other’s experience but I have sensed that 1 gb of projects from SVN or GIT seems to get done faster than downloading a 1 GB executable and an unpacking through the exe
  • Also as IT departments look to lock down more device administration in the name of cyber security, source control tools aren’t locked down as much as executables.
  • Different versions of the help could easily be change through with branch switching functionality.
  • Help updates could also be distributed faster, especially errors.

[NovotnyJ (Jan Novotny)]

I try to write in my own:

In download section (documentation for HW) it’s don’t remember the language, so I always must change the language. “Lot of” my start-up work is offline (there is no signal in the dam and sometimes it is a wilderness where I have to walk 15 minutes to get to the internet). I would appreciate the ability to open the card datasheet directly from the HW configuration - downloaded with AS or automatically with the project.

I prefer offline, because the web is slow (I don’t know, if I am alone, or more people have it slowly).

Finding in help is very complicated for new things, which I never do never before. As @marcusbnr or @kovarj mentioned.

I would prefer instructions and examples. Not how to make it work, but how to use it correctly in a broader context.

@Frederic_Boyadjian have good point about HW catologue. Some “excel” sheet, where will be mentioned main parameters of IO, like number of DI, DO, AI (with types), AO, counters, maximum load,… . And another for CPUs, BC, …

And most important to end! The Context help!!! When I write some program in ST, there is no “intelisense”. With functions it’s 2/5, but for FBs, there is no support (show sometimes on first write, after it’s show only FB definition in *.var). Still need to open the definition or help. Please add it and improve the graphics (some colors). Not only help, but interface between help/definition and using it in program. Something like this:

These are my observations that were not included in the summary. If I am wrong, I would be happy to be corrected or directed.