This article has been contributed by Rafał Pawlicki, Senior Developer at DreamLab Poland, a company providing IT services and solutions for digital media.
I had the pleasure to meet Rafał already at soap! conference last year, where I spoke about our SUSE documentation processes. Back then Rafał and I discussed a lot about the importance of documentation, and the relation between documentation and developers. I was really very much surprised to learn that he liked working on docs – as a developer!! (Well – if you follow my blog, you probably know that “documentation and developers” is one of my favorite topics 😉 …). We also spoke about how they handle docs at DreamLab. Thus it was really great to see Rafał live on stage at soap! 2018 with his talk “How did over 300 skeptics start writing docs?”. These developers at DreamLab understand that documentation is an essential part of a product. And of course I couldn’t resist asking him if he would contribute an article about his experiences with documentation to the SUSE blog.
Here you go – enjoy reading!
IT projects and building software products can be dumped down to adding new features and fixing some bugs. In general, it’s all about making changes that will increase the business value of your solution. In most cases, this process contains phases like: analyzing, planning, development, testing, and release. Is that right?
If so, where does documentation find a place? Should and can documentation be an essential component of the product, or is it a nice (but just still an) addition? Maybe it should be required before every release? When should we write our docs?
I’ll try to answer these questions – based on my 10+ years of experience as a developer. In addition, I will try to present some methods that can be used to create documentation. And I will point out a right place and time when documentation should be written. But first and foremost, I’d like to inspire you to start a discussion about documentation in YOUR company.
When Do We Need Documentation?
The answer is simple: ALWAYS – but of course not always in the same form. If you are working on a simple application or kind of a library, in most cases a README (a short description and basic installation guide) and a few examples will be good enough. On the other hand, if your project is more complex, you should cover the full range of documentation: implementation guides, user manuals, some maintenance instructions, etc…
Should internal tools or applications also come with documentation? This is a question which I heard quite often. The answer is obvious, if you change this question a little bit – for example to: “Would it be helpful to read the documentation before you start working with an internal tool?”. It is not important if your product will be used by external users or by your teammates sitting right next to you.
In general, regardless of the format, we all need some introduction before we start working with a new system. It doesn’t mean that your docs always need to have 435+ pages and some annotations. In many cases, documentation doesn’t need to be extensive. Richard Feynman once said: “If you can’t explain it in simple terms, you don’t understand it well enough”. Keep this quote in mind when you’re about to write some documentation!
In any case, your readers should know what the document really is about, how to run the application and what the important features are that they can use.
Is Documentation a Part of the Product?
This is another question that I heard many times while working on our documentation. At least in software, there is no „self-explanatory” solution. There is no product which is so simple to use and maintain, that it doesn’t require any description, introduction or examples. If you really believe that kind of optimistic assumption, you might easily wake up in a different reality, in a place where you need to run some support line to answer your users’ questions. This can cause huge costs, that can be avoided if you invest some time in writing some documentation.
IKEA might serve as a great example here: Even for the simplest product they have in stock, they provide a (usually easy to understand) instruction. IKEA products would not be the same, maybe even would not sell so well, if they could not be assembled by customers – based on information delivered by documentation.
And if you plan to sell your product as a ready-to-use solution, documentation becomes mandatory. If you think of an IT project at a customer’s site, usually the manual is the first thing that lands in the users’ hands. Many times, customers decide if they will buy your products or not based on what they will find in the product description respective the user guide. On a smaller scale, regarding, for example, a simple application or library level, the same is valid: first of all, you would like to understand if this really is what you were looking for – and it would be great if you could check the documentation.
How Should We Write?
I had the opportunity to attend the soap! technical communication conference in May 2018. Several speakers presented a few concepts which I will write about in this post because they are related to the most important aspects of creating a good quality documentation.
Special thanks to Natalia Woszczek and Paweł Kowaluk for great talks, which allowed me to answer the question in the header of this subsection. You might want to watch the video recordings of their talks here and here.
The most important part is to know who will be your reader(s). If you know that, you are able to adjust your language and your form of communication. Your text, content, and writing style will be different if you write for a technical guy or a business-type person. For example, you will probably use different paradigms, explain other stuff differently or more in detail, maybe you will even cut some content.
On the other hand, there are some aspects that you should ALWAYS focus on, regardless of the audience. Text needs to be understandable – that’s obvious. But what does that mean? How do you know if your documentation is easy to read and understand?
First of all, you need to learn a little bit about successful communication patterns. A good example for that are the plain language guidelines. They tell you clearly what „simple text” means. This concept is used by Federal Institutions in the U.S. They set a goal: Write documents in a way that they can be read by everyone
- by educated people
- by people who did not graduate from university
- by people with disabilities or dysfunctions
- regardless of age or social class
Another example is the ASD-STE100 specification, which details how to create technical documentation. The primary idea of this project was to simplify the English language, so that even the non-technical reader will understand everything. This posed a huge problem to airline companies. In most cases, their passengers did not know English well enough to understand and follow the general instructions (including the safety guides). This problem was caused by language complexity, ambiguity, and a very specific vocabulary. If that sounds interesting, I would strongly suggest reading more about those concepts.
If you want to create better content, you can even revert to machine support. There are software solutions that analyze content automatically. I’m not talking about such obvious aspects as syntax or grammar check. Advanced solutions can also check the complexity, content form, etc. There are plenty of tools available, but from our experience I would recommend the following: Hemingway Editor, acrolinx, readable.io and HyperSTE.
The tools described above require documentation written in English – which, in many cases is the language you write in anyway, especially when writing about technology. Sometimes the translation process can take some time, but if your customers are from different countries, English might be a better choice than your native language.
Documentation as Part of the Process?
If you already know when you need the documentation and how to write it, you should consider when will be the right moment or time frame to write it.
Many companies employ (teams of) technical writers. This is great! Technical writers have deep knowledge about content and communication which is why the documents they write usually contain high-quality content. The job of a technical writer is to describe your product or solution in detail, so that your customer can use it. They review the business requirements and needs with the product teams to understand their audience, they discuss the features and new technologies with the engineers to understand technical aspects, they collect and generate information about how the features and technologies are implemented to make it easy for your customers to use your products. In the end, the technical writers are responsible for providing a full range of documentation related to new features and technologies, or to the entire product. Depending on the project, documentation is written during the development process, or when a product/feature is ready. In both scenarios, some things might change – so it’s important to keep documentation up-to-date and verify that your content describes exactly and only what was actually developed.
At DreamLab we had to approach this issue in a different way. Currently, we don’t have technical writers on board. But what we do have is a bunch of developers (300+), mature development and deployment processes, and a checked bulletproof work methodology.
For our purposes, we assumed that writing documentation should not interfere with the developer working cycle. Our developers shouldn’t switch their context because they needed to describe some feature. We found that, if they are actually working with their code all day long, documentation also could be written much like code. There is a concept of writing docs based on comments from the source code, used mostly to generate Reference Manuals (functions, parameter descriptions, etc.). We decided to expand this idea and write our user documentation in that way. We found that we can store our entire business documentation inside the repository, close to the application source code. We also decided to use plain text format for the writing – and we chose reStructuredText (reST), which is understandable from the beginning and can also be used to generate documentation in many fancy forms.
During the development of a feature or product, our team writes some „docs as code”. They are in the same context, and all of the tools are in one place. That saves a lot of time and everything can be kept up-to-date. When a feature or a bugfix is ready, source code and documentation are verified (they pass code review) and deployed to the right place (as it is in the continuous development process). The rest is kind of done all by itself: Our processes and tools take care of publishing the documentation in the right format and at the right location.
Documentation is needed. It is an essential part of the product and it has a huge business value. It allows reducing costs and gaining new clients.
Depending on the project, the audience, or the purpose, documentation can take different forms. Often it does not require thousands of pages with sophisticated text and languages or complex sentences. Content should be simple and understandable for everyone. In an ideal scenario, documentation is part of the software development process. This reduces the time that you need to spend on writing and publishing it to the right spot.
If you don’t have a proper documentation department, our example – how we changed the way of creating documentation at DreamLab – shows that if you use existing and proven solutions, developers can write documentation. Embedding these writing efforts into the processes that you already have in my view is crucial.
Writing docs should be a continuous process of improving communication and increasing quality based on previous experiences. This is why, even today, we’ve got plenty ideas of how to drag more developers into our new trend and encourage them to write some documentation. We also want to check out several new tools to create our docs in an easier way.
Coming to the end, I will leave you with some questions: Are you aware of the importance of documentation? How does the documentation process look like in your company? Do you contribute to documentation?