My name is Iryna Isay and I am a tech writer at WePlay Esports media holding which is part of the TECHIIA holding. In my previous article, I talked about conducting a , its approaches, and best practices. And right after it was out I received a lot of questions from colleagues and those who are thinking of switching to technical writing, how to actually draw up and structure the documentation.
So in this article, I will share my experience. It can be useful for both product teams and tech writers. These are not rules but advice from my own experience and life hacks that I learned from my colleagues.
This article will be useful both for rookies (people who have just come into the profession and want to understand where to start and what mistakes to avoid), and tech writers who have skills and made their own mistakes. My experience can become an inspiration to such people in finding new solutions in creating documentation. At least I'm always interested in how my colleagues create documentation.
In this article I’ll talk about the following:
- where to start when you get a new product to outline;
- what should be avoided when preparing documentation;
- what to do with the documentation that was not created by you, and is of low quality, and whether it is worth working with;
- a little about documentation tools.
"It’s fancy, just draw it up"
I really like to create the technical documentation of a product that wasn't outlined by anyone before me. This approach has certain advantages: I can create the structure of the documentation, make rules for its formatting and style approach. But this does not mean that you can just sit on the beach near the ocean and, inspired by the summer breeze, write a novel.
First, I recommend you interact with everyone who is involved in the development and support of the product in any way: communicate, gather information, learn the product.
Here’s a tip. Sometimes the product team is anxious about giving access to the full product and you can learn everything from the trial or test version. It doesn’t work that way. More than once I had to redo my work because a trial or test version and the final product were different. Even the interface can differ a lot.
And product teams often "experiment" with the names of fields and various buttons. Sometimes there are "fun" names on the verge of censorship — in any case, they should not get into a decent product manual. Take all screenshots only from a well-designed UI of a real product that you can reveal to the public.
The next thing to do is to review the technical documentation available: use cases, technical requirements, etc. I like to check product teams’ Jira boards and gather information from them. We collect and structure everything (you can even put it in a table for convenience). But even at this stage, when it seems that there is some understanding of the product, it is too early to write the manual itself.
When you have gained access and learned all the information available (or still in the process as you started to see some logic in the information received), it's time to test the product.
For example, ISO recommends creating profiles for your readers:
- Who are the users of the product you are going to outline?
- What tasks do they seek to solve with the product?
- What are the user levels and how the product performance differs depending on these levels?
The tech writer needs to get into each such user’s shoes, go through every customer journey, and actually solve the tasks with the product. Sometimes it's boring. Sometimes you have to do the tester’s work again, perhaps even more meticulously. But the result is worth it, your manual will be thorough, like a real work of art. It will have a beginning, the main part, and an ending.
The beginning can vary. You may need to describe the product homepage first. Sometimes it makes more sense to start with a description of the user's account. Don't worry, you will understand this somewhere at the testing stage. And sometimes you will just be told what should be described in the first place and what should be left for later.
Things I avoid: levels, rules, promises
I do not make the documentation too deep in levels. From my experience and on the advice of colleagues, I know that if you are not a Boeing, where each article can have a subtext or ancillary or related articles, then your documentation should have 3-4 levels tops. If you have more (manual, guides, articles, sub-articles), no one will read so deeply, because it will be difficult to find the information needed.
I came across some examples when tech writers did an individual article for each new feature. I’m not saying it's bad, but it's a slippery slope. For example, your product is a complex analytics tool that can be crowded with additional features. Or these features are replaced by new ones in no time. As a result, there are so many articles that they are hard to find in the documentation. Moreover, it becomes difficult to see the whole picture of the product.
Here’s a tip. Start with top-level articles — descriptive, which will be an introduction to the product manual or a particular feature guide: what’s the product about, what are its features, how to use them.
When there is a general description, you can go down to lower levels — to a specific feature (or its elements). A small introduction to each guide or individual articles that explains what the user will read next is of great help as well.
I add the table of contents to each article when possible (this can be done, for example, using Confluence) or use different levels of headings (for PDF for example). Be sure to remember: no one will read the entire manual and each of its articles. The user will run through the table of contents, then the headlines, perhaps paying attention to the colored blocks with tips and screenshots. But will focus only on what the user is looking for.
At the end of each article, I give a link to related information- additional or related features. I never make links in the middle of the text: in PDF not everything is clickable, in Confluence links can break when exported to another documentation tool. As a rule, I create the Read more section at the end of the guide and add a few links to the list.
When you already have a “skeleton” — the upper level of documentation — and some “muscles” on the lower levels, it becomes clearer what features should be put in the documentation and where.
I often use Confluence to work with documentation. Here I keep a glossary, a version table. It’s also useful to have an article (an individual document) about user and system roles — access and permissions in the product you're outlining
Already at this stage, we begin to understand how best to name guides and articles, even section titles. The main thing in the titles is that the reader intuitively understands and finds the information needed.
I don't start working on the documentation without understanding my own writing standard. Headlines for example. You need to decide exactly how you write them: as a sentence (with the uppercase first letter, the others are lowercase); each letter is uppercase; with or without pronouns…
Here’s a tip. Headlines are my favorite. Sometimes I come across an acronym that I can't even imagine what it's about. Sometimes, on the contrary, you have two or three lines of text in the title and you totally forget what it was about once you finished reading it.
I have a rule that the title should fit in one line, or even in half a line, if possible, that’s even better. Always remember that your reader can use devices with different screen sizes, and the text can have different formats: PDF, HTML, etc. Hence the problem with the length of the line and the ability to read it. It can be cut by the screen field, and you should not irritate the reader, but give him the opportunity to see all the text at once.
I write more in English, so I try to make headings with active verbs: "delete__", "create__". When a person is looking for an answer, the manual should show a specific action to be performed.
But it is not always possible to put an active verb. In that case, you have to make the title more explanatory. It has its advantages: the reader will see the description that will help find the solution.
Formatting headings and fonts are best done after writing the main material. To do this, it is useful to have such a documentation tool, that allows you to apply styles to all texts and adjust them all together. You may find my tips on how to choose one down below in the corresponding section.
I do not write about something that does not exist. Sometimes product teams tell about some upcoming features and even show a test version. They also can promise to fix, finish something tomorrow, in a week, within a month, which will significantly change the product interface or its features. That is, they hint that it can already be described, so as not to rewrite later. Never fall for that! It is impossible to describe the expected. What is on the screen is in the documentation.
Work stuff
Let me tell you about some complications every tech writer faces.
There is a button but there’s no function. That’s quite common, to be honest. Product teams do not always want to keep their technical documentation, so they often remember only the latest about their product. They know everything about the new button, but as for a little older one, you will have to look for information elsewhere.
It's even more frustrating when such a button or any other element is there but it just doesn't work. You can ask the team to hide it, remove it, but this is not always possible, there is not always a resource for such a task. In this case, I ignore this piece, do not describe it. Although there’s still a risk that the user will find this nuance and start asking about it. It can be a bit awkward then. But, as a rule, the user is interested in finding specific solutions in the documentation and misses such “nuances”. The tech writer’s task is to provide the user with helpful information.
Feel free to simply accept such things, because the product is a living organism, it is constantly changing.
Sometimes, for example, there are more surprises with the product elements’ names. When two teams work in parallel, or one was replaced with another straight away. They created something and everyone called it the way they like. For example, some named the same button “Add” and others called it “Create”. Seems like it’s not a big deal, right? But, firstly, I always adhere to consistency, and secondly, there is a big difference between these two verbs. In this case, I suggest that the teams agree and dwell on one name, give them an explanation with references to dictionaries, what is the difference.
I run a small internal channel for teams in Slack. There I talk about grammatical and stylistic details and give examples of best practices in writing technical documentation.
Word-difference explanation and recommendation example
I also try helping WePlay Esports’ and TECHIIA’s product teams: I created a unique guide for them about style, abbreviations, grammar, etc. These are simple and concise notes so they can check once needed.
Horrible documentation. It's harder to work with documentation that someone has already written for you. Sometimes such documentation is a total nightmare both in structure and content. There is probably some explanation for this, but it is not worth taking the time to find and understand it.
Part of such documentation might be useful, that’s why I usually leave everything unchanged and go back to the essential articles and fix some of them only when necessary. You can understand which ones of them are essential while using the product. We rewrite such documentation, adapt it to the existing style, and send something to the archive. It takes about a year to work with already written documentation. Yes, it's really long: a partial audit, fixing "horror" parts, archiving inessential articles (sometimes it's better to describe everything from scratch).
Sometimes a company wants to keep previous versions of documents to show the evolution of a product. But even for this process, you need to have instructions on how and what to archive, keep versioning, and so on. Of course, that’s a tech writer’s task, you need to have a whole bunch of your own internal rules and standards.
If you have a choice between creating documentation from scratch and everything I just described, I advise you to prefer the first option. There is a certain pleasure in creating a whole world of documentation out of nothing. But raking the Augean stables is a dubious joy.
Here’s a tip. If you have many teams to work with and many products to work on, you can try to apply the CI/CD principle (continuous integration/continuous delivery), maybe even to work with the documentation created before you.
I learned this from my colleague David Bailey. He offers to teach product teams to create their documentation on their own. The tech writer’s task, in that case, is to monitor the process, provide recommendations, standards, conduct ongoing training, advise on point-by-point issues that are in doubt.
The whole documentation is not prepared at a certain point of product development but goes through the entire life cycle. In this way, it becomes more meaningful and carries more useful information
Choosing documentation tool. This one is about technical writing tools and how to choose one for your tasks.
Before you buy something, you need to be aware of all the work processes with documentation, understand how you write, store, publish ready-made documentation, what are the requirements and needs of the reader.
I tried everything before I made a decision: I used different software for almost a month and tried several demo versions. Then I gathered all the information in a table, analyzed all cons and pros, and as a result, I chose MadCap Flare.
If you are interested in the whole selection process, what options I had, their advantages, disadvantages, my own opinions about each tool, write about it in the comments.
MadCap Flare screenshot
And now, having MadCap Flare at my disposal I use it to do the following:
- to write absolutely all articles. We also publish them in Confluence for product teams, and this is a certain "backup" of information;
- to format styles and texts in one place (usually PDF, HTML5 formats);
- to keep all your glossary with definitions;
- to constantly support all "variables" — these are generally proper names according to the glossary. They can be conveniently replaced from one source in all manuals if there is such a need;
- to have a guide for this tool on all main points: style, grammar, work with visualization, etc.
Tips for beginners
In our part of the world, the tech writer’s job is relatively green, it is just being formed. Sometimes different IT resources don't even have such a category to see vacancies or learn wage estimates. Therefore, it is difficult to outline "industry" standards, and each tech writer can experiment at his/her own risk.
The first tip is to look for best practices, read the manuals of companies that have a history and reputation. They know the drill. They have entire departments working according to their own internal standards and policies. Each of their decisions for documentation has long been justified and makes sense. So you write exactly as they say, and as written in the instructions, like a machine. But there is no room for your own vision in this case. However, as I mentioned before, I do recommend you learn best practices from such companies.
As an example, I will give a and its in particular.
Google also offers compelling technical writing courses for developers, yet they will be useful to everyone: ;
The second tip was mentioned before, and it is to understand the product in the first place, to document the architecture, to create your own standards, and lay down the rules for writing it.
Sometimes people ask me to show my way of doing it. Firstly, not everything can be revealed. If the document is not publicly available, it is most likely confidential. Secondly, it is of no use, it will not help another tech writer, because everyone has their own users and they have their own needs. Just replicating it will not work.
The third tip is not to copy, but to work on your own approach. Working in a market with an unformed tech-writing tradition means getting involved in shaping the game rules. And this has its little joys.
A short tech writer test
In conclusion, I want to say that there’s nothing to be afraid of. Working with documentation is interesting if your soul and brain are set up to structure any input information. But if you consider yourself a tech writer just because you can write in English, I have to disappoint you. Our profession is quite boring, you need to be able to sit down and deal with the product in detail. It requires a lot of effort and time for self-development, and this is a never-ending process.
A good tech writer is one who pays attention to details and looks for the opportunity to properly document anything. For example, how to take a screenshot from a Smart TV without a special device? It's good if you work at Samsung and have a lot of tools at your disposal.
For those who thought about taking the photo of the TV screen, access to the world of instructions, guides, and manuals is denied for now.
But if you read the instructions to a new gadget, notice the weak points, and want to rewrite it straight away — congrats, you have passed the tech writer test! Welcome to our community.
Here I’d like to add my favorite READ MORE. The list goes on and the following links are just for inspiration:
- ;
- ;
- ;
- ;
- .
Original article on .
