Documentation is not a compulsory task, but an opportunity to increase user, developer and customer satisfaction. When we think of documentation, we think of the thick paper manuals that come with every product.
There should be instructions for use between the legal texts. Is that good documentation?
No. Documentation should help people to use the software correctly, understand the purpose of functions, work more efficiently, train people, look up forgotten facts or exchange information.
Why is most documentation so bad?
Yes fine, you still have documentation. Here are the top reasons why:
Too much, too little, non-existent: the amount of docs is hard to choose. By default, no docs are included or 600 pages long.
Documentation about obvious things: Technical writers and developers often only document the obvious. At the top right is a button for processing. But nobody explains the process of processing and why it can go wrong.
Old: The software makes great leaps and bounds, while the documentation is neglected. Old documentation and screenshots are a no-go.
Babble and compulsory form only: Many developers have no interest in documentation and therefore only write to fill the pages and keep the boss quiet. Neither the boss, customers nor anyone else reads it.
Nobody wants to read it
Prior knowledge: Documentation is often incomprehensible because the developer does not document a lot of secret and prior knowledge. For him, everything is clear and plausible. For others, it is a useless manual.
Addressee overwhelmed: A developer needs different documentation than a user. A user is not interested in what new customers want to know. Documentation needs an addressee and many forms.
10 top tips for better documentation
1. See documentation as an opportunity – not a burden
Documentation is often the number one chore when asking developers. Nevertheless, I encourage you to reconsider your opinion. Your documentation celebrates the successful completion of a feature or release. The doc shows that not only can you code, but you can easily teach the software to others. You can look back on a feature and recap what you’ve done.
I consider Doku itself to be a good change from programming. While you often spend hours on end in the same place (bug) when programming, you can just keep going word by word when writing documentation. You have a final product that grows and improves with every additional minute.
2. Milestones and word count
Keep yourself motivated with milestones. Keep yourself visible – I have already documented 8 out of 20 features. I have already written 1000 words. Every day I write 200 words on a feature before development. Avoid hasty actions and document a little every day.
3. One sentence of documentation is better than none at all
1 sentence is often more helpful than 600 pages of manual. The developer / documentation writer should rather do less than push the super documentation in front of him as a task.
Nobody wins a prize if you have a long documentation.
In the first sentence, you can introduce the motivation behind the software or draw the developer’s attention to the development environment.
Often we just need an easier start. Tell yourself that you will write 10 minutes of documentation and then stop. As a rule, the start is the most difficult and you quickly forget that you only wanted to write for 10 minutes. On days when nothing works, you can stop after 10 minutes and continue programming.
4. Who reads this documentation – technical language?
The addressee is often unknown. Documentation must be customised for the addressee. The user does not need to know anything about API routes and the new customer does not need a tutorial. There is no such thing as 1 documentation, we need many short, customised documents.
New customers: Prices, top 10 features, comparisons between software types
Existing customers: Tutorials on features, processes
Admins: How do I install the software? How do I manage users?
CEO: Pricing, strategy, problem solving
Developers: API documentation, comments in the code, coding environment.
Developer documentation is important
5. Formatting is king
Good docs are structured with headings and subheadings and include tables and charts. Users should be able to find topics easily with the table of contents and glossary and not have to read chewing gum texts.
6. Simple solutions are the best
We can spend 30 days discussing what the best documentation software is. Nevertheless, the simplest formatting method – markup or MS Word / LibreOffice – is usually the best option. The technology is available to all, fast and uncomplicated.
We want to minimise the barrier to writing the first sentence of the documentation. Collaboration can take place via SharePoint or Git – the main thing is to avoid sending version 1.1.1-update-new-docu.md via email.
7. Don’t be afraid of pictures, screenshots and diagrams
Pictures say more than 1000 words.
Always use the best way to convey information. If your documentation consists of 1000 screenshots, that’s ok. A “quick” video with a screen recording is better than any text you can write. All audio and video files should be short and broken down into mini-topics rather than recording a mega-blockbuster of 240 minutes.
8. Set reminders – keep up to date
Keep the documentation up to date! Regularly check your calendar to see when you need to update the documentation. Every release is a good time to check the documentation.
Splunk does it right
You can version the documentation at the same pace as the software. Even if nothing has changed, you can use the new version to confirm that it is still relevant.
9. Nobody benefits if you use complex language
In scientific writing, many researchers think they have to express themselves as complexly as possible in order to show off their intelligence. However, the art lies in explaining facts simply and concisely, while technical terms are explained immediately.
Documentation should inform and not frighten with technical language.
Simple language consists of short and medium-length sentences with active verbs. We present facts neutrally and do not digress from the topic. We delete every sentence that we can save.
10. Every new feature, a new section in the documentation
Even if everything is a matter of course for you as a developer, you should mention all features in the documentation. Not everyone knows the shortcuts that work in the new software. Otherwise, “hidden” features will remain hidden from the user. The feature development time is then considered wasted because nobody uses the feature.
Leave a Reply