OnScale’s engineering software features both a graphical user interface and a powerful scripting tool.
The syntax documentation for the scripting tool was held in a bloated Adobe RoboHelp project. To further complicate matters, OnScale held only a single RoboHelp licence, meaning developers were unable to contribute to the documentation directly.
I migrated the syntax documentation to Markdown and published it via MkDocs. In addition, I moved the documentation to the same GitHub repository that held the code, allowing developers to easily propose documentation updates at the same time as they made code changes.
WordPress for user documentation
Upon the launch of their new product, OnScale Solve, OnScale were keen to provide a seamless experience for users when navigating from the main website to the user documentation.
Another requirement was for the engineering team to be able to contribute to, and review, the documentation directly, and not be “locked out” of the process either by requiring a product licence or by having to learn a new tool.
Given these requirements, I decided to implement a documentation solution in WordPress, which I had previously used extensively, but never for documentation.
By setting up the WordPress backend with a few carefully selected plugins, I was able to replicate some of the functionality that is normally found in dedicated tools for technical writers, such as MadCap Flare. For example, I was able to implement “snippets” (reusable pieces of text).
The result is a lightweight solution that meets the original requirements and is also great for OnScale’s SEO (search engine optimisation), since OnScale’s documentation content now helps to drive users to OnScale’s website. You can check out the solution for yourself.