Markdown-Documentation in Automation Studio

Ask Questions B&R Software & Runtime
1

How do you organize Markdown-based project documentation in Automation Studio?

I’m currently looking for a good way to maintain project documentation in Markdown directly in an Automation Studio project. I don’t want to go into the many disadvantages of older formats, such as .chm or .doc, at this point. Markdown should be the standard, especially for version-controlled projects.

The documentation can contain text (in .md files) including tables, code examples and of course also images. Markdown works very well for editing and version control, but Automation Studio does not provide a graphical Markdown view. I’m therefore wondering how other users organize this in their projects. I know that AS code and VS code can display md files in a graphical view, but this is not useful for Automation Stidio (without code).

For example, I see a few possible approaches:

1. Separate documentation folder at project root

Project/
├── Documentation in md/
├── Logical/
├── Physical/
└── project.apj
This keeps the documentation clearly separated, but it is not visible within the Logical view in Automation Studio. And the “nice” view is only visible in the git repository view.

2. Markdown files directly inside Logical

This makes the documentation part of the project structure and is easy to find from within Automation Studio.
However, the Markdown files are only displayed as text there, so the formatted documentation with images, tables, etc. is not really convenient to read.

Project/
├── Logical/
├── Logical/Documentation in md/
├── Physical/
└── project.apj

3. Markdown at project root + rendered documentation inside the project

For example:
Project/
├── Documentation/
│ ├── *.md
│ └── images/
├── Logical/
├── Logical/Documentation/Documentation.html
├── Physical/
└── …
The Markdown files would be the source, while the rendered HTML documentation could be opened in a browser.

4. Another approach?

Maybe there is already a common or recommended way of handling this that I’m not aware of?!?

  • How do you organize project documentation in your Automation Studio projects?
  • Do you keep it at the project root, inside Logical, or use some kind of generated/rendered documentation?
  • I’m particularly interested in approaches that work well with Git/version control and can be maintained directly with the project.

Thanks for your answers!

3

Hi Samuel,
you have already very clean and smart idea our to organize the documentation inside Automation studio.
Unfortunately I have seen too many prjs where the documentation is not updated when we change the code (in particular during commissioning) so I’m very curious what we can do with free AI tool to maintain the documentation (for sure for ST and ladder languages :slight_smile: ).

Ciao
Valerio

4

Hi @Samuel

It’s maybe a little out of context, but I’ve developed a python script to convert B&R library to chm help file automatically.
Of course it didn’t solve the documentation of a whole project but it can help for library documentations.
And it’s not based on markdown but on HMTL due to chm file, but it follows the way Automation Studio handle chm help file for libraries!

Here is the original post about it:

Hope it can help!

Regards,
Florent

5

Hello @valerio.manenti, @Samuel,

In regard to documentation and AI tools, I created as-docs tools, which should make docs of the AS project, and is enhanced by AI.

It generates searchable documentation for B&R Automation Studio projects written in Structured Text (IEC 61131-3). It scans the project structure, POUs, tasks, variables, data types, call graph, and data flow, then writes Markdown, JSON, llms.txt, and Mermaid output.

This was created for me only, so it hasn’t been fully refined down to the last detail.

6

Thanks a lot for all your feedback!

I think there are actually two different topics here, and I would like to keep them separate.

1. The content of the documentation (was not my main question)

Creating and maintaining documentation is, of course, always a challenge (or a pain :wink:). Very often, documentation is not created at all. Even more often, it is created once but not maintained afterwards as @valerio.manenti mentioned, so it becomes increasingly outdated over time. If the documentation is stored in a format that is difficult to edit, such as CHM, it can become very difficult to update it without access to the original source files.
For creating content, there are the tools that can automatically generate parts of the documentation. However, with today’s AI capabilities, I think automatically generated documentation is becoming less important.
The most valuable part of documentation is not necessarily what is already directly visible in the code and can therefore be generated automatically. Much more important are the things that cannot be derived from the code. For example:

  • pictures and diagrams
  • explanation of algorithms and concepts
  • explanations of how something works
  • the reasoning behind a particular implementation
  • information why it is solved this way and not another way

These are the parts that I consider particularly valuable in project documentation.

2. Format and location of the documentation

2a. Location of the documentation

This is actually what my original question was mainly about. Regarding the location, @alexander.hefner and I had a separate discussion about this.
An Automation Studio project consists of different elements such as libraries, tasks and packages, which can contain different types of content. In our opinion, it makes the most sense to keep documentation as local to the documented object as possible.

For example:

  • Documentation for a lib directly within the library.
  • A package implementing a specific function should contain the documentation describing that package.
  • Documentation that applies to the entire project should be located at project level.

This still leaves the question of exactly where project-level documentation should be stored:

  • On the highes level in the project parallel to Logical and Physical
  • Or whether it should somehow be integrated into Logical.

2b. Format of the documatiation

In times today with git, I think only Markdown (.md) as format makes sense.

But there is the general problem that Automation Studio (without “Code”) itself does not provide a nice graphical way to display .md files. Markdown files are basically just shown as text, so you don’t get the formatted layout, tables, embedded images, etc.

I think there may not be a perfect solution for this. In some cases, automatically generated HTML could be an option to provide a nicely formatted view, including images. However, this introduces another potential problem: the generated HTML can easily become outdated if it is not regenerated whenever the Markdown source changes.

So my main question is really about the best way to structure and store documentation within an Automation Studio project, rather than about automatically generating the documentation itself.

What do you think? How do you handle this in your projects?

7

Hi @Samuel ,

as we’ve already discussed, my experience has more theoretical nature as I’m not doing projects anymore. Nevertheless, at least I’ve a opinion about :wink:

About 2a.
In my opinion, also the project-level documentation should be part of the projects logical view, so integrated into a top-level package in Logical.
Why? Because then for every user of this project it’s at least totally clear, that some documentation exists! I won’t swear that everybody would take attention about documentation, if it’s not shown in the AS project view.

(Initial) adding documentation into Logical view can mean some extra-effort (especially if the’re subfolders used, which have to be packages from AS point of view) → so yesterday I tried to use AI to build the AS Package structure for some bigger documentation pack (including several subfolders with images linked to the md file), which worked very well → so AI can not just support creating documentation, but also by putting it into the AS project with structures and package administration files needed by AS, which keeps the additional effort integrating documentation into AS Logical at a minimum.

About 2b.
I totally agree, I don’t think there’s a perfect solution for that. But when having a md-Viewer installed in Windows, which is additionally set as default viewer on system level, let you open the md file by double-click on it in AS logical view → in my opinion that’s “good enough”, even if it’s not perfect (as an external editor is needed). So I’m not sure if a HTML documentation in parallel is really mandatory?
But thinking about conversion from md to HTML, at least some automatism would be possible, for example triggering the “HTML out of md”-update by a git pre-commit or pre-push hook? BTW: what do you use for md to HTML conversion, is it Pandoc?

BG Alex

10

Thanks @alexander.hefner for your reply!

After giving it some thought and considering the discussion here, this is the conclusion I have come to:

  • Documentation should be kept within the Logical View. Otherwise, there is a good chance that it will simply be overlooked. Keeping it close to the actual project content makes it much easier to find and maintain.
  • In the Logical View keep it as close to the sources as possible: Inside libraries, inside tasks, inside packages …
  • Markdown should be used as the documentation format. It is simple, text-based, easy to edit and works well with version control.
  • I would avoid converting the Markdown files to HTML or another generated format. I tested this approach with Pandoc and MkDocs, and while the result can look nice, it also requires additional build tools and a certain amount of knowledge about how to use them. Not every developer will have these tools installed or be familiar with them. This can eventually lead to the generated “nice-looking” version no longer being updated and therefore becoming outdated. As Alex already mentioned, there are also tools that can be installed to display Markdown files in a much nicer way when double klicking on it in Automation Studio
  • One additional point that I think is important: Documentation generated automatically - whether by AI or other tools - can only contain information that is already available somewhere in the code or other existing project data. It may be presented in a nicer way and perhaps enriched with diagrams or other generated visualizations, but it can never capture the developer’s reasoning behind the implementation. Why was this solution chosen instead of another one? What constraints or considerations led to this approach? What might look unusual or unnecessary in the code but actually has a specific reason? → For me, these are exactly the parts where manually written documentation adds the most value.

So, at least for my projects, I think Markdown documentation directly within the Logical View is the most practical approach.

11

@Samuel,
Thanks for this very good summary, and for starting this valuable discussion!

@kovarj, @martin.altenberger, @hubert.brunner: from my point of view this discussion & outcome could (should?) be taken into consideration for some future discussions about standards?

Regards, Alex

12

agree, can be taken to consideration and included either to Clean Coding or SW architecture training module or AI and Agentic Engineering Getting started Workshop. I take this point and will try to move it to proper people :slight_smile:

13

To my understanding reading through the thread, this is probably not a topic where B&R needs to create extensive proprietary training content.
Of course participating external training on GitHub, DevOps etc. will have a value for engineers as SW engineering is emerging into automation.
So I am also curious if someone can put recommodations here.
Discussion seems to go more into the direction of well establishd working principles in SW engineering I understood the follwing:
How can project documentation become a part of an Automation Studio project while remaining maintainable, readable, and version-controlled?
Write documentation once in Markdown, keep it under version control with the project, and automatically provide a user-friendly rendered view for engineers.
Code, configuration, documentation, and knowledge should be managed together in a version-controlled ecosystem.
So, the discussion is less about teaching engineers a new skill and more about bringing Automation Studio closer to software engineering standards that are already widely established.