This fall’s Digpro Lab intended to explore user documentation – how the tools for creating it can be improved, and thereby also be easier to read for the users of our Network Information System (NIS).
Lina Lokander, Technical Writer at Digpro, initiated this autumn’s Digpro Lab Project together with Christer Folkesson, Senior Developer and Pontus Lindström, Team Manager QA. She spent an intense week working together with Christer and developers Emiliano Kloster, Radha Ravi and Jakob Kratz. The Digpro Lab team is provided with a designated space as well as endless supplies of snacks and beverages. Usual work tasks are put on hold, and all focus is on exploring the project, which is executed by asking questions and finding answers.
Three areas to explore
“We had three major areas where we wanted proof of concept”, Lina relays. “Firstly, we wanted a new and modern way to build the system for the user guide. Secondly, we intended to find out if we could use GIT for version management with the documentation tool which we use today. Thirdly, we endeavored to handle diffs, this to support the person who proof reads the texts we write.”
For the first part, the developers found a build system that would meet the demands of complex user guides. A number of key concepts were identified, adapted to Digpro’s needs, and stress tested accordingly. For the second part, the ability to use GIT for version control was explored.
“This part proved to be perfectly fine, and I will now be able to use the same version control for the technical documentation as the developers do for their code”, beams Lina. “And for the third part, I am pleased that it will now be easier for everyone to review texts.”
With some TLC from the programmers, changes in the user guide are now clearly visible.
“Our technical documentation is written in XML or HTML”, explains Lina. “And now, all changes are converted to snippets where colors indicate the edits. New text is highlighted in green, and deleted text is highlighted in red and marked with a strike through. This makes it so much easier for the proof readers to know what they should focus on.”
Positive results for the user guide
Overall, Lina is very happy with the Digpro Lab week. “The user guide is an important part of the utility systems that we provide. It was really luxurious to have four such competent developers dedicating their minds to the tools we use. Watching them work was impressive. One second, they are all engrossed in lively discussions. The next, they are absorbed by the task at hand in front of their own computers. Knowing that all this time and focus were spent on user documentation, which has a tendency to be a bit in the background of a system, was a true bliss”, she concludes.
About Digpro Lab
Digpro Lab is a week for innovation, during which different techniques or ideas are tried out. These are suggested by anyone at Digpro, and are compiled into different projects. One project is chosen for each spring and fall, when Digpro Lab is held.
Digpro Lab is a popular activity for Digpro employees. Learn more about working at Digpro at our career pages.