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!