Can software developers and technical communicators write documentation together? How parson supports Siemens in setting up a collaborative authoring process
The Siemens division "Digital Industries, Factory Automation, Information Management" wants to make its technical documentation fit for the future and has therefore developed an authoring process for joint documentation by software developers and technical communicators. parson evaluated the proof of concept.
Initial situation: Separate documentation, no standardized authoring process
Software developers and technical communicators write documentation separately. Software developers store and manage their documentation in Git repositories. Technical communicators write documentation in a component content management system (CCMS), which they then convert to DITA-XML, merge with the software developers' documentation, and enrich with metadata. The technical communications team also manages translation, quality control, and approval processes.
The goal: Joint documentation and a standardized authoring process
Siemens wants to create a standardized authoring process for software developers and technical communicators. The goal is to reduce authoring time and effort and improve quality and delivery.
Towards a solution: Concept for a standardized authoring process
Siemens has developed a joint authoring process for both roles. The process consists of the following steps:
- Software developers create documentation using the docs-as-code method. This allows them to stay in their familiar development environment.
- Git repositories serve as a central integration system using DITA-XML.
- A standardized metadata vocabulary is used for all documentation.
- There is a standardized approval, translation, and publishing process.
- The technical communications team coordinates the documentation process to ensure quality.
- Documentation is published through the Fluid Topics content delivery portal.
parson evaluates proof of concept
The parson experts analyzed and evaluated the Siemens proof of concept, focussing on the following aspects:
- Integration: Git repositories as the central integration system using DITA-XML as the integration format and Oxygen as the integration tool
- Working environment: Different tools and file formats used by software developers and technical communicators: Visual Studio Code, component content management system (CCMS), Oxygen XML Author, Markdown, and DITA-XML
- Authoring processes: Review, approval, and translation
- Quality assurance: Repository consistency, templates, and validation for Markdown and DITA-XML
- Content delivery: Metadata management for publishing to the Fluid Topics content delivery portal
Concept paper and user stories
parson documented the results of the analysis, including a risk assessment and suggestions for appropriate countermeasures, in a detailed concept paper. In addition, parson provided Siemens' requirements for the planned solution in the form of user stories.
With these two documents, Siemens has a solid foundation for implementing a standardized authoring process.
Next Steps
- Align formats, processes, and tools
- Define translation strategy
- Integrate AI into daily processes and gather use cases
- Run a full release with new processes
About Siemens, "Digital Industries, Factory Automation and Information Management"
For us, it all starts and ends with our customers. Maximizing value for them is what drives us! Combining the real world of automation with the digital world of information technology opens up completely new possibilities for our customers in all industries. In this way, we empower them to make better decisions and enable them to accelerate their transformation to become a Digital Enterprise. With our unique portfolio, we can make a decisive contribution to sustainable industrial innovation – transforming the everyday and creating a better tomorrow for societies and people around the world.