Software documentation 101: Introducing a technical writer

Purpose of software documentation

At the very beginning, you have to ask yourself: what’s the purpose of your software documentation? These can differ of course, depending on your client’s needs, they can request different types of software documentation.

The most popular example of documentation is a user guide – it describes how to use a specific application. This type of written documentation should provide a clear and quick answer to any questions the user might have so that they can complete their tasks. Technical writing in this type of documentation can include screenshots of the app, e.g. with marked buttons that need to be clicked in order to achieve a specific action. A well-written user guide usually equals an easy-to-use application, which will certainly make your end client happy.

Another type is technical documentation – it contains all the technical information, such as the type of frameworks, database and API used in the application. Which, in turn, allows you to keep track of the app’s progress and improve its quality. Preparing technical documentation requires basic technical knowledge, so not everyone can do it.

And, finally, there’s compliance documentation. Actually, I’ve heard about it for the first time at The Software House. The concept wasn’t introduced in the course of my studies, but these can sometimes suffer from quantity over quality, so I’m not really surprised. But what type of documentation is “compliance documentation”? Let’s say your client’s application will soon be subject to an audit. For bureaucracy-sake, he/she will have to present the documents on literally everything related to the app. From the app’s appearance to where the user inputs lands in the database. This type of documentation needs to be very accurate in order to meet the audit’s requirements. For that particular case, we’ve created the following documents:

• Presentation – all frames (views) located inside the application, with labels for all the text that appears in the app,
• Flowcharts – transitions between the frames of the application,
• Google sheets – contains the written text obtained through the above presentation, plus the tracked data, such as the type of input field, answers, validation, business logic, and the place in the database.

Why choose a non-technical person?

The next thing to consider is: who should write your software documentation? Surprisingly, the best answer might – be a non-technical person. You might think that he/she won’t be able to grasp the project’s details and will just slow down the team, but my experience taught me otherwise.

As I mentioned above, a technical person is needed only for one type of documentation. In our case, the client chose the third type – compliance documentation. Initially, the scope was small, but then #GDPR came, forcing us to create a detailed documentation of the whole application. A rapidly increasing number of requirements generated more and more documents. One QA simply couldn’t handle writing it all, but we were reluctant to add another one because it would increase the cost and remove him from another project.

Then the idea of using a non-technical person came up. We considered everyone who wanted to be introduced to the IT world or liked working with computers.

After that, we decided to present this approach to our client. We believed that such a person (later called “technical writer”) would be cheaper than an experienced QA, and, after being properly introduced to the application, would write software documentation of the same, or even higher quality. The client agreed to our proposal but asked for the technical writer’s work to be reviewed by the QA during the first weeks.

How to find a technical writer?

A technical writer doesn’t need to have experience in IT or even a degree in technical studies.

For us, the most important thing was the knowledge of English, Microsoft Office tools and flow diagrams.

At first, we feared that such a person would feel lost in our company and project, but our doubts quickly disappeared. All thanks to an introduction plan, which I will present to you in the following paragraphs. It turned out that the key was the pacing – everything had to be dosed in order not to frighten the new employee with something he/she had never heard of. On their first day, I told our brand new technical writers that they’d work with databases. Their expressions were priceless. Now, after a short introduction, they work with the data from the database better than I do.

Why couldn’t your QA write all the software documentation?

During the first weeks of our project development, a QA did write all the software documentation. That QA is me. In the beginning, it was like a part-time job, but after the app had been tested, I was asked to document all the text inside. Then the client made a presentation in front of his/her business associates so that they could decide which part to change. The client also inputs all the changes in the appropriate excel columns for the devs to easily locate them. In time, I received more and more requests, and I gradually stopped testing the application, which had a negative impact on its final quality. We were wasting both QA time and the client’s money, which could instead be spent on 2 or 3 technical writers. For a similar price, we’d get the required software documentation much faster.

How to introduce a technical writer to IT?

So, it seems that we found the perfect solution. A bigger team means faster delivery, and this, in turn, translates into a happier client. But how can you introduce your new technical writer to the vast world of software development?  Here’s a guide compiled from everything I’ve learned.

At the very beginning, build a system for creating software documentation: set workflow in Jira, create a compendium of knowledge about the project (access data, everyone involved in the project, everyone on the client’s side etc.) and build templates of documents that will eventually be created.

Introduce the technical writer(s) to the whole team, and take them to meetings during the first weeks of work.

It may seem unnecessary because they will be a separate team, but it creates an attachment to the project and shows them how to work with Agile.

Create a software documentation workshop. Invite the technical writer(s) and a front-end employee who will be able to answer questions about the app view. As a QA, I was able to present the whole app on a projector, together with the logic of its operation. Any doubts were cleared right away.

Give the technical writer a day or two to consolidate the knowledge gained at the workshop, and then ask if he/she has any questions about the application’s logic. If you succeeded in making the writer interested in the application, he/she will probably have many questions, so prepare for them. Having a lot to ask about the app means that the writer is beginning to understand it. If there are any doubts about the logic, use well-known comparisons, like Facebook or Google.

When the technical writer knows the application, show him/her how software documentation is created – ask about the knowledge of the tools, present those that are unknown and write an example using them.

Should the technical writer participate in project meetings with the whole team? No. In my opinion, it would be a waste of time. He/she neither works with the whole team nor does he/she need information about their current progress. I think the best approach is to organise daily meetings and retrospectives for the technical writing team. Then the client will be able to participate in meaningful meetings on the progress of the documentation.

The system works, but what’s next?

Don’t leave your technical writer just yet. During the first few weeks, review his/her work and tell him/her about the best practices in the software documentation field. Rome wasn’t built in a day – software development is not easy, mistakes will be made and you have to learn from them. Communication is vital, so always ask if your technical writer needs help. This way, you will prevent him/her from thinking: “if I ask about something obvious, they’ll laugh at me”. In my book, asking questions is the best way to go, and I’m always happy when someone does. Then, sometimes, I have an opportunity to learn something new as well.

Finally, remember that, from time to time, technical writers need to be reminded of their purpose.

Self-development is a good thing, but you can focus on it after you’ve delivered the main part of your work. It’s not worth wasting time on improvements that won’t be used.

Summary

You may still be reluctant to hire a non-technical person for writing software documentation, but I promise you won’t regret it. I introduced three technical writers to our team, and while they were creating the required documents, I could return to my duties as the project’s QA. This is a win-win situation – the client is satisfied with the quality and speed of the project documentation delivery, and our QAs can focus on their role in the project (besides writing documentation) which is to guarantee the high quality of the code.