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 right 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, and they wanted Orbis Technologies to provide consulting and expertise as a documentation partner.
The team at Orbis Technologies 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 analysis findings were critical to developing an effective documentation solution that would meet Critigen’s needs.
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 Orbis Technologies knew that keeping the documentation up to date meant keeping pace with the software development team. Orbis Technologies established the documentation effort as an integral part of the software development life cycle. This approach immersed Orbis Technologies into the development environment and fostered a stronger partnership between the two groups.
By doing the analysis, Orbis Technologies identified three main types of information that needed to be addressed by the documentation.
- Introductory information —This is documentation that 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 —For the technical stakeholders, Orbis Technologies developed more detailed descriptive content so potential decision makers could learn about technical elements that might affect their IT environments.
- Detailed instructions — Orbis Technologies developed 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, Orbis Technologies implemented several documentation tools. These tools complemented Critigen’s software development publishing framework, meaning that documentation builds could be stored and packaged with Critigen’s existing software publishing tools.
- Single-source authoring — Orbis Technologies implemented 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 — Orbis Technologies 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 – Orbis Technologies developed an interactive documentation website as a 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 website and the documentation website.
A key factor in making the Critigen-Orbis Technologies partnership a success was the level of integration between the Critigen stakeholders and the Orbis Technologies project team, which was comprised of a project manager, solutions architect, technical writer, editor, and technical illustrator. The Orbis Technologies 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 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 Orbis Technologies team—skills and experience that would be hard for them to replicate internally.
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 Orbis Technologies meant that Critigen could focus on building its software without worrying about documentation.