5-Minute Tools for Product Leaders: 7 Principles for Pretty Good Documentation
Tamás Varga
Senior Growth & Product Manager | Creating Strategy & Leading on Execution | Building High-Performing Teams | eCommerce, SaaS, Online Travel
Documentation is not what you usually learn in formal education. For years, I did not have tools I found very useful and efficient, and perhaps as a consequence, I did not really like creating project documentation either. In this article I will share the story of how I wrapped my head around, along with principles I today follow to make documentation feel useful, efficient, and eventually fun.
Principle #1: Consider documentation as a product with an audience and a job.
My approach to documentation changed fundamentally when I first had to document a system from scratch. Starting to work on the assignment, I talked to a former business analyst colleague, to help figure out what tools to use and how to get a hold of the task. At one point in our conversation, he told me: “When you map a flow, you always map it from a certain perspective. There is no such thing as a universal flow documentation.” Those two sentences made me realize that documentation is not about creating a perfect representation of reality. It is more about finding the right goal and the right perspective first.
For finding the right goal, I argued to myself that the documentation is ultimately also a product, which should solve a certain job for a certain target audience. In this case, I set the goal that the documentation should:
For finding the right perspective, I had to realize that when you want to learn about something from the scratch, the question you usually ask is what it is. The answer however is more along the lines of what it does, for who, and in what context. For example, if a child asks you what a ship is, you probably will not describe that it is a vehicle constructed of wood or metal, can range in size from 10 to 200 meters, and has a more or less oval shape. More likely, you will reply that a ship is a large vehicle that stays afloat on water, and a few or hundreds of people can board to navigate in lakes, rivers, or in the sea.
In this case, internalizing this difference felt particularly important, as the system performed primarily backend jobs that were never visible to users. Thus, trying to describe what the system was by describing its visible features was simply not an option. The solution came from taking a perspective to describe what jobs the system solves, via what flows, how those flows work, and in what larger context they fit across multiple systems.
Once I laid down the goal and the perspective, the rest became a lot easier. I defined how long the documentation roughly should be, based on the targeted reading time. I collected with colleagues the key flows and the jobs the system served in the flows it took part in across multiple services, the interfaces users could interact with, the base terminology, and on top of that linked out to other materials for details.
Sadly, the assignment was ultimately deprioritized before I finished it - more on that at principle #5. But, I still learnt a lot about how I would approach documenting in the future, while leading development projects on an ongoing basis. Lets continue with that!
Principle #2: Don’t necessarily stick to a single document - create a network of materials.
As I started documenting during projects more systematically, I argued to myself that in the agile development world and the age of the Internet, where things can change pretty fast, and where you are very much used to navigating on a web,nbsp;you do not necessarily need to add everything in a single document. Instead, you can create a central hub that helps understand the bigger picture first more easily, and then help navigate to details in a second step.
Thus, I typically work with documentation for bigger projects as follows:
1. First, I start out with tools that are most suitable for synthesizing business requirements collaboratively.
2. Once the requirements and plans are in good shape, I create a Confluence page. This is mostly for development, and once created I use it as the central hub, and add details at QnA and link to various destinations for additional information. It follows the below structure:
3. As the project comes towards the end, I create additional documentations from different perspectives as needed, and link in the Confluence page - like an internal FAQ or a separate documentation on some specific rules. I may also create sub-pages for some bigger topics. I edit the central hub’s core parts, other teams could also add to the QnA and the sub-pages under the main wiki.
Thus, I ultimately get a network of materials structured like this:
With this approach, there is no need for all details to be in a single very big document. There is a single place where you get a general overview, and can navigate further for some particular details.
Princple #3: Accept that some documentation is better than no documentation.
A common argument against documenting too much is that it becomes obsolete. Like any product, documentation has a lifecycle - this is good to accept to have realistic expectations around it. If you expect that your documentation will stand the test of time, you will most certainly be disappointed. The fact that one day it will become obsolete should not be a reason for not documenting however, like it should not be a reason not to launch any product.
Related to this, it is perfectly fine to have some documentation with more details, while others with less, depending on the value that the documentation will provide. If you manage a really complex project that will shape the next 2-3 years of the fundamentals of a system, you probably want to have it significantly more documented than if you are introducing a new dropdown on the UI - a good user story can perfectly solve for that.
Principle #4: Do the work to make it nice and understandable.
Once you have a pretty good structure, you should still put the work into making your output pretty good to process. On top of the basics, like structuring into paragraphs, bullet points, etc., I am listing below some tips I learnt during my career on writing and flowcharting.
1. Aim for concise wording and shorter sentences. By removing unnecessary words and shortening sentences, reading becomes easier. This has been a particularly hard one for me, as by default I tend to write precise sentences and stuff in as much information as possible. I often re-read and scan for refundant words and simplifying sentences before publishing.
2. Use consistent wording. Swapping words for the same concept makes it harder to maintain associations. For example, if you use the word “customer”, do not use “client” as a substitute. Swapping is great in artistic context, less great in documentation context.
3. Form sentences using linear logical order, instead of using reversed logical order. While reversed logical order is more artistic, linear logical order takes less energy to process. See the following example:
领英推荐
4. Use active verbs for flowcharts. It is usually easier to read, emphasizes the act more and makes it easier to empathize. See the following example:
5. Write avoiding unnecessary jargon. Fancy words words sound more professional, but make processing more difficult.
6. Use colors. For flow mappings I use up to 5-6 colors to identify different actors and help form associations on who is doing what. I also put some effort into making materials look a bit stylish - its more fun to work with them.
7. Use a dedicated tool for flow mapping. Before SaaS tools appeared, I used to work with Excel to map flows - even if writing this down makes me feel a bit like a dinosaur. Miro meant an order of magnitude jump in quality and ease.
8. In flow mapping details, format to make it look good. Refer to sub-flows if a flowchart becomes too complicated, and add an end-of-flow indicator to flows - small thing, but helps closure.
For more tips particularly on writing, check the Udemy course Writing with Flair: How To Become An Exceptional Writer.
Lets put all this together, and take a look at how this can add up to an example I made for the purpose of this article. The wiki below describes an imaginary project, where a company introduces a cooperation to 20€ gift vouchers for travelers making a reservation, provided by another company (Company B).
And, a flowchart for receiving a promo code could look like this:
Principle #5: Document as you specify.
It is a good idea to pay attention to the quality with which you specify and document as the project progresses, for a couple of reasons:
It avoids having to work on a big documentation project that few people really like to do, can be quite difficult to finish without priorities shifting by the time it would finish, and parts of the system may actually change by the time it finishes.
Taking notes and specifying on an ongoing basis properly solves a large chunk of project documentation, as with relatively low effort you can re-use them completely, partially, or with some editing. Sure, at times you need to come back to revisit what has actually changed in the previous materials during ongoing discussions. But, you will have a good basis you can copy, update or edit, instead of having to create a big documentation from scratch at the end.
Principle #6: Accept that people will ask you, even if you have pretty good documentation.
No matter how good documentation is, there will be situations where some details are not covered, some parts have become obsolete, or it is just faster to ask people in a situation that needs a quick resolution. This is not necessarily bad either - people helping each other out also builds relationships, as long as noone takes advantage of the others helpfulness.
Also, it is not realistic to expect colleagues to simply find and read your documentation. They are working on several projects with several points of contact and several links to resources. As product leader, people will ask you for an overview or for details. You cannot avoid this, but you can make your life easier if you have good documentation that you can just pull up or send along. Like any online product, documentation needs traffic, and the primary traffic source will be you.
Principle #7: Archive periodically.
Last but not least, by doing some hygiene work and removing obsolete pages, you will help both yourself and others navigate useful content easier.
+1: Enjoy the benefits!
Following the above principles has helped me get to a stage where I can say that documentation for me has become pretty useful, efficient, and eventually fun. It feels good to see when things are flowing easier, thanks to less ambiguity and quicker resolutions. Even if documentation is not perfect, just pretty good, it can help with a lot of small steps forward, and those small steps can add up to a pretty big step forward.
-
This article has been the 3rd part of a series with the goal to help product leaders grow, by describing practical tools I have found useful throughout my career. The articles aim to find a sweet spot between being short enough to read in 5 minutes and long enough to inspire to try, explore or initiate discussions on them. Even if this one was more like 10 minutes - oops. Stay tuned for the next one!