When documenting software, you need to react quickly and flexibly. Short release cycles, agile working, and constantly evolving software versions are specific requirements that technical editors are confronted with in software documentation. In addition, in order to be able to describe software correctly, the editors must also use and understand the software themselves. In the process, it can happen that they stumble over one or the other software error. However, this doesn't have to be an obstacle, but can lead to positive synergy effects.
How can this be achieved? We've summarised the key points for you.
Work agilely
The agile way of working that's common in the software environment requires that a product must usually be documented during development. For this purpose, the work packages to be completed in software projects are planned in short stages (sprints). This creates flexibility, provides the opportunity for prioritisation, and ensures that work can be done in different places at the same time. However, this way of working also means that work packages and thus software features change and develop quickly. This poses particular challenges for technical editors: It quickly happens that documentation falls short and can't keep up with rapidly-moving software development.
How can this be prevented?
Due to the constant change and the required flexibility in agile working, in our experience it makes sense to involve external technical editors directly during sprints and the planning of work packages. This gives them a good overview of what's currently being worked on. They can directly follow, assess and consider the effects of the current work packages on the documentation. This is particularly helpful if the documentation phase is to take place at the same time as development and must be available shortly after the development is completed. In such a case, work and documentation usually have to be done under considerable time pressure. If this doesn't succeed, the new information must be labouriously tracked and subsequently incorporated. This can be prevented by cleverly integrating technical editors into an agile way of working.
Additional advantages are: Agile editors quickly find their way into the work environment and thus gain a holistic overview of the state of development. They recognise which features should be documented at which point in time. They know at which points there are possible difficulties that require special attention during the documentation process. They're also able to make subsequent adjustments at the right places in the documentation if changes, further developments or dependencies in the software make this necessary. In this way, the documentation always remains both up-to-date and technically correct.
→ The integration of technical editors into an agile way of working is not an obstacle, but offers the potential to provide documentation on time and to keep it up-to-date and correct.
Understand, test, and improve
The first step to correct documentation is to understand the software. Like end users, technical editors must familiarise themselves with the software step-by-step. This helps them to take on the user's perspective and identify the specific information needs on the user side. Their view of the relevant information is additionally sharpened by the learning process during the testing phase. In comparison, this view is only available to a limited extent among developers, due to their familiarity with the product.
However, it doesn't have to remain the case that the editors "only" understand the software in the context of documentation creation. In order to further increase the quality of the user information, it's proven helpful if technical editors use the software attentively and thus test the documentation and software together for usability. This interface between software documentation and software testing can provide positive synergy effects: using and testing improves the practical knowledge of the software, and creating documentation improves the theoretical knowledge of the software.
Our experience with this approach shows that editors can take over test cases over time and identify bugs, for example. A significant advantage is that the increased involvement in software engineering enables technical editors to directly assess the influence of bugs and other errors on the documentation and thus better plan their own work. In this way, software quality can also be continuously improved over the course of documentation creation. These synergy effects are also driven by the fact that the skillsets of editors and software testers overlap to a certain extent: You have to be able to work precisely, think through every eventuality and – the most important point – communicate results precisely and understandably.
→ A combination of software documentation and software use leads to both the quality of the software and the quality of the user information being improved.
Optimise specifications
It's not only for the end users of software that information must be prepared in a comprehensible and error-free way. Well-maintained internal specification documents are just as important so that Development teams can use them as a guide. This ensures consistency during development and prevents unnecessary questions and potential errors. The key requirement: internal specification documents must be well-structured, consistent and clearly understood by all stakeholders. This also includes a well thought-out versioning concept that's capable of correctly mapping different software versions. In the development phase, this can reduce many queries, unnecessary coordination and deviations. Technical editors who are involved in software engineering at an early stage can make a valuable contribution to improving internal specification documents.
→ Checking and improving the consistency and quality of internal specification documents can positively influence software quality.
Publish correctly
When publishing user information, it's important to use the right medium and the right format. In the software sector in particular, the trend is clearly pointing in the direction of digital user information, while the traditional manual in paper format is becoming less and less important.
Due to the ease with which digital information can be updated, those responsible for documentation are under particular pressure to ensure that software instructions are always correct and up-to-date. Close interaction between Development and Technical Editorial also offers a decisive advantage here: editors who are closely involved in the development process can react immediately to changes, further developments and dependencies in the software. In this way, new information can be documented and implemented much more efficiently than would be the case with downstream documentation creation.
In order to exploit these advantages in publication as well, the content must then be made available in the right place just as quickly. Online Help and information portals can be a useful solution here.
→ By involving technical editors in the entire software development process, user information can be provided better and faster in the right format.
Our conclusion: Get information experts on board as early as possible.
Technical editing as the underappreciated last link in a long information chain? Modern, agile process models show how things can be done better, especially in the software sector. The basic idea behind this is clear: consistently focus the project on user benefits. To achieve this, it's important to integrate the technical editors into the development process right from the start. On the one hand, this makes documentation creation much more flexible. On the other, as experts in usability and comprehensibility, the editors can provide valuable input to the Development team. Whether it's a question of operating procedures that are difficult to understand, misleading terminology, or meaningless error messages, the greater involvement of professional "information mediators" can make a decisive contribution to avoiding correction efforts and achieving a higher quality of results.
