Challenge
Critigen is an information technology services company that developed a software platform to help companies integrate geographic mapping data with other business software applications, such as asset management, work management, field data collection, and other applications that leverage location information.
Critigen knew they faced three key documentation challenges that they expected to be addressed by a robust solution:
- The software was evolving rapidly, and ongoing updates were going to be the norm, requiring that the documentation also evolve at a rapid pace.
- Due to the complexity of the software, it was important to give internal and external audiences (both technical and non-technical) the appropriate information, so they could understand, implement, and use the powerful capabilities of the application.
- Critigen did not have the in-house expertise to develop and implement a documentation plan that would meet their needs; they needed consulting and recommendations from a documentation partner.
Solution
The Contiem team began by performing an analysis to gain a better understanding of Critigen’s software platform, the software development environment, and the needs of those using the software. The findings were critical to developing an effective documentation solution.
A key factor was that Critigen was using two-week sprint cycles to drive Agile development. The software platform was in a state of ongoing improvement, so Contiem knew that keeping the documentation up to date meant keeping pace with the software development team. Contiem established the documentation process as an integral part of the software development life cycle. This approach immersed Contiem into the Critigen development environment and fostered a stronger partnership between the two companies.
Contiem identified three main types of information that needed to be addressed by the documentation.
- Introductory information — defines basic concepts and explains the business context for the application. An important part of the documentation package, this information provides baseline insight for all audiences.
- Technical overview — more detailed descriptive content for the technical stakeholders, so decision makers could learn about technical elements that might affect their IT environments.
- Detailed instructions — system-level documentation to support implementation teams, so they could set up and configure the software in their own environments. This information provided context for the very detailed information written and embedded in the code by Critigen’s software developers.
To support content development, Contiem implemented several documentation tools and methodologies. These techniques complemented Critigen’s software development and publishing framework, meaning that documentation builds could be stored and packaged with Critigen’s existing software publishing tools.
- Single-source authoring — Contiem introduced MadCap Flare, a single-source online help authoring tool, and used it to develop in-depth knowledge articles that could be reused across document types to explain concepts and provide task-based instructions. The articles focused on promoting a deeper understanding of what the software could do and how to use it according to each audience’s specific needs.
- Dynamically-generated content — Contiem implemented GhostDoc, a tool that extracts development notes embedded in the software’s API code. With this tool, Critigen’s developers could provide insight into key functionality while the code was being written. Combined with the task-based help content, the dynamically-generated content provided critical support to implementation teams.
- Documentation website – Contiem developed an interactive documentation portal to host all of the knowledge articles, system-specific documentation, technical API information, and software documentation. It was designed to align with Critigen’s branding, providing a seamless transition between the corporate and documentation websites.
A key factor in making the Critigen-Contiem partnership a success was the level of integration between the Critigen stakeholders and the Contiem project team, which comprised a project manager, a solutions architect, a technical writer, an editor, and a technical illustrator. The Contiem team members were brought into the project as needed, in order to keep each deliverable on schedule and on budget. With this approach, Critigen did not have to worry about varying staffing needs to meet peaks and lulls in their software development life cycle. Plus, Critigen was able to take advantage of expertise about documentation approaches, tools, and techniques from the Contiem team — skills and experience that would be hard for them to replicate internally.
Result
Critigen saw real results in a very short time:
- A comprehensive content plan, addressing the different target audiences and the information needs of each group
- Performance-focused tools, supporting the demands of developing the required documentation in a fast-paced environment
- Documentation process efficiencies, enabling alignment with the software development life cycle
- Improved user experiences, empowering users with the information they need to successfully implement and use the software
Working with Contiem meant that Critigen could focus on building its software without worrying about documentation.
☰ Menu
