parson AGAutomate technical documentation with docs-as-code
For user-friendly developer documentation
Technical documentation is typically created from content modules so that several authors can collaborate, content modules can be versioned and several variants can be published from the same source. Software engineers have similar requirements for managing their source code. Also, a lot of technical documentation is written by software engineers. They want their documentation close to the code so that they can update the documentation along with the software and publish it when the code is released.
The docs-as-code approach addresses these challenges: It treats the documentation in the same way as the software's source code. The documentation is versioned in the version control system, written in integrated development environments, and published through continuous integration pipelines. Multiple authors can work on the documentation at the same time. Automated workflows make the documentation quickly available: close to the code, consistent, and always up-to-date.
We implement docs-as-code
We implement a docs-as-code environment for your software documentation. We select suitable tools, develop an information architecture, and integrate the documentation into the tool landscape of your software engineering teams.
parson also creates software documentation, developer documentation or API documentation for you using the docs-as-code approach. This is how we work.
Your contacts
Docs-as-code
Our customers
Docs-as-code for user and developer documentation. This is how we work
- Analyze requirements. We work with you to analyze the requirements of your target audiences. We set up a suitable docs-as-code environment, using tools and formats such as AsciiDoc, Markdown, or DITA-XML.
- Develop pipelines. We create publication pipelines that automatically generate formats such as HTML or PDF. We then integrate the publication scripts into your build environment to automate the publishing process.
- Define workflows. We help you define documentation workflows as part of the development process. This may include, for example, managing the documentation tasks in an issue tracker like JIRA.
- Define repository structures. We define the repository structure and branching strategy for documentation within your version control system, such as Git.
- Develop information architecture. We create an information architecture for documentation and develop templates and terminology lists for your authors, whether they are technical communicators or software engineers.
- Integrate quality assurance. On request, we integrate scripts and writing rules for automatic validation and checking of content, for example, based on a linter like Vale, which analyzes natural language based on patterns.
- Select and set up tools. We help you select and set up the tools you need to create and publish content, for example, to a developer portal. This includes editors such as Visual Studio, IntelliJ, or Oxygen XML Author, as well as static site generators such as Antora or Jekyll.
Learn more about the docs-as-code approach in our FAQs.
FAQs – Frequently asked questions about docs-as-code
What is docs-as-code?
Docs-as-code is an approach to creating and delivering documentation for software. Docs-as-code means that you treat documentation the same way you treat source code. The docs-as-code approach combines two important aspects:
- You use the same tools for the documentation files as the developers, such as IDEs (integrated development environments), version control systems, and tools for continuous integration and delivery.
- You use the same methods as the developers, such as agile project management and Scrum.
What are the benefits of docs-as-code?
Docs-as-code offers many benefits, here are a few:
- Cost savings. By using the same tools and processes for software development and documentation, software companies can save money. There is no need to purchase a component content management system (CCMS) for software documentation.
- Versioning and collaboration. With version control systems such as Git, multiple authors can work on the documentation at the same time, tracking and editing changes as they occur.
- Workflows. Automated workflows ensure that documentation is created, tested, and published automatically.
- Author integration. When authors follow the same workflow as developers, they are fully integrated into the product development process.
- Engineers as authors: Software engineers can contribute to the documentation more easily because they don't have to change environments.
Which tools are available for docs-as-code?
- You need a text editor, such as Visual Studio Code or IntelliJ. Developer documentation is often written in a lightweight markup language such as Markdown or AsciiDoc. You can also use DITA-XML in a docs-as-code environment.
- For version control, you can use Git, for example.
- As a continuous integration tool, you can use Jenkins, Bamboo or the integrated GitLab CI to publish content stored in the version control system's repository.
- For output to HTML, you will need a static site generator. However, most static site generators only generate very basic HTML pages. For technical documentation, you need advanced features such as versioning or search integration. Only a few site generators offer these advanced features, such as Antora (AsciiDoc) and Sphinx (reStructuredText).