Áina Rocha and Filipe Franco, Technical Writers, @SISCOG | 4 min read
___________
From Lisp to Python coding, from different systems and diverse products, the User Documentation team is formed with one mission:
to create a clear guide to support end-users in their journey through SISCOG’s software products.
ONCE UPON A TIME
It all started just like most things do: out of necessity.
Whether it was from forgetting how to perform certain steps of a software operation or from finding it difficult to understand how the products work, it became clear that SISCOG’s software products needed a documentation process to support clients in planning and managing the use of their resources.
However, the user manuals were not always produced by a designated team. At the very beginning, most of our user manuals were produced by testers while working on the products, using conventional writing software as the main tool. It soon became evident that due to the multiple operations available in SISCOG’s products, and the different customisations of SISCOG’s systems, the development of user manuals would need a much more stable foundation.
When our current writing software tool came into the picture, the testing team had already composed many files containing how-to instructions about our products. Yet, it was clear that dealing with that amount of data was a full-time job. And that’s when the User Documentation Team was born.
The User Documentation team's mission: to create a clear guide to support end-users in their journey through SISCOG’s software products.
______________________
MASTERING USER DOCUMENTATION
One of the main challenges in writing documentation about SISCOG’s products remains in mastering the differences between systems - the product that is adapted to a client’s reality - and making sure that the user manuals are as accurate as possible, as well as updated, according to the newest releases from the products, such as ONTIME, FLEET, and CREWS.
Our current software tool helps us avoid writing the same page for each system’s user manuals. Instead, we can tag any piece of text that contains a system’s particularity so that it only appears in the intended system’s user manual. That way, as we gather all the details and write instructions about the system’s functionalities, operations, or concepts on the same page, we can also generate a completely different page for each system.
Surely, keeping the user manuals updated is a daily job. As we keep up with the products’ release notes and participate in Agile teams, writing manuals about SISCOG products and systems that keep on evolving is a challenging task that demonstrates the significance of teamwork and cooperation with other departments.
Now, with files that cover instructions about the main operations, and software that provides us with structure and tools to work with, we can focus on writing improvements and methods that assist the user comprehension when facing SISCOG’s concepts and software operations.
A good practice to earn the user’s attention and deconstruct complex concepts into smaller and clearer thoughts is by using flowcharts and diagrams, as we do for the "Reality Tree" concept in the example below.
Example of a diagram that illustrates the "Reality Tree" concept.
Other than that, another approach to conceive the user manuals as a smooth reading is to use GIFs to exemplify the steps we describe, and the results expected from an operation. To avoid exhaustive reading, we use the "Every page is page one" (EPPO) method, so each article corresponds to a different question and is independent from each other.
To facilitate navigation, the user can open the user manual directly from the SISCOG software when pressing the F1 button over a menu option. This action will open the user manual on a specific article with how-to instructions for the menu option.
We believe how-to articles are a good solution on a day when your memory fails, and you can’t remember the order of steps to operate. However, it does not provide details and explanations that allow you to understand the logic behind the process.
For that, we diversify our documentation type.
Empathy as the future
In an effort to provide all the necessary support to the software users, writing a user manual is like an exercise of empathy: As an end user, what would be my questions? Difficulties? What would I struggle to remember?
By placing ourselves in the end user’s shoes and gathering feedback from surveys, we realise that their necessities go beyond how-to instructions. We need to answer not just the "how", but also the "what" and the "why".
Following this perspective, we aim to write diverse documentation that includes tutorials, explanatory articles, and FAQs.
Different documentation types have manifestly different goals, and, therefore, produce different kinds of support for the end-user. While we explore our products in search of questions that the end user might have, we also strive to find the best way to get the message across effectively.
Writing a user manual is like an exercise of empathy.
______________________
Just like our products are constantly evolving, so too should our documentation.
Instead of settling for standardised documentation, we are always looking for new ways to improve and innovate our approach to aiding our clients and meeting them on the different stages of their learning journey.
And though it’s been a challenge, the knowledge and experience we’ve gained has been incredibly rewarding.