Work Smart: Automate Documentation

Maestro is a complex product, having a modular structure. This means it consists of different elements, or modules, that can be set up and used altogether or one by one, if necessary. The majority of the tools are CLIs that need to have setup or quick start guides, reference guides, usage instructions and scenarios, etc.

Each element needs to be documented separately, and the documentation needs to be maintained timely.

This gives quite a big piece of work for either the development or documentation teams, or even both.

However, Maestro team invented their own tooling for automating CLI documentation management, and this both significantly decreases the related daily effort, and facilitates keeping all deliverables to the same style and format, irrespective of the person who creates them.

The custom documentation tool operates via a focused, repeatable pipeline:

md → .docx → .pdf

This process separates and integrates two content types:

  • The static content, such as setup guides and tutorials, is written manually in Markdown (.md) files.
  • The dynamic content, which is the up-to-date command reference, is automatically generated from metadata (like a JSON file) by a script. This ensures the command reference updates whenever the CLI tool source changes.

The workflow leverages three key components:

  1. Markdown is the source of truth for both manual and automated content, favored for being Git-friendly and easy to edit.
  2. Pandoc acts as the bridge, handling complex format conversion and incorporating features like page breaks to minimize manual formatting.
  3. DOCX is the final output format, used for reliable conversion to professional PDF documents for clients.

The proposed solution is not just a script for generating files. It is a reliable approach that builds a strong bridge between the developers of the CLI tool and its end users, ensuring that the documentation remains up‑to‑date, accessible, and professional.

For more information and the link to the tool, see Oleksii Olchedai's Medium blog post: Automating CLI Documentation: From Code to PDF in Seconds

Popular posts from this blog

Maestro Meets Microservices to Expand its Open Infrastructure Platform

Image
In our previous post , we discovered Maestro as a part of the Open Infrastructure world, as well as its Open Source components and strategy. However, a modern platform is more than just about infrastructure. To increase efficiency, unification, visibility and control, it is important not only to establish effective infrastructure management, but also to set up control on the application layer. With the infrastructure layer being often hosted in multi- and hybrid- clouds, Microservices became one of the silver bullets for cloud-based and cloud-native applications within the past years. They allow to package your applications properly so that they can be hosted on any platform. The parts that cannot be put to this type of architecture, are often re-platformed, or re-architected within the new provider. Thus, a modern platform should be capable of both managing Cloud environments and empowering microservice-based applications development, delivery and management . Kee...
Read more

Enterprise Cloud Billing: Adjust and Conquer

Image
Maestro billing engine allows transforming virtual and hardware capacities utilization into bills , based on the events within their timeline, and states they get as a result of such events However, the modern world, with its dynamic changes in situations and requests, needs flexibility – and in billing, as well. The hourly cost of your datacenter maintenance may depend on external factors, like varying electricity costs (for example, cheaper night hours), which can let you make nightly hours of your infrastructure usage be also more affordable. You may also want to re-distribute the load between data centers or data center sections during peak hours by offering lower prices in underutilized zones, and higher prices – in those that are overloaded. Season discounts, special offerings, and other pricing alterations are also on the list. You even may want to apply extra charges for your users access to public clouds, by adding a respective coefficient to the native provi...
Read more

2025 is coming: From Dragon Tales to Snake Wisdom

Image
The Year 2024 is coming to an end, and it's high time to sum up our achievements and future plan in the traditional summary and resolution post. While the Green Dragon is still here, we would like to start with summing up the past 52 weeks, taking the recap of the updates, news, and success cases we had - all that becomes a solid ground for our further movement. 2024: Main Steps and Updates Traditionally, Maestro development was focused on several main directions, as well as included a set of general updates and stabilization changes. General updates and stabilization The updates covering general Maestro performance and core functionality has been taking place throughout the year, with the massive stabilization closer to the end of the year. These included not only performance improvements and bug fixing, but also important new features, such as the possibility to have the ReadOnly access to Maestro, a huge update to C-level, tenant-l...
Read more