History of the LumApps help site (2/3)
In the previous episode, I wrote about the shortcomings of the first version of the LumApps help site, and some unfortunate implementation decisions we had made. In this article, I will focus on how we tried (and sometimes failed) to improve.
Several — if not all — of the suggestions below are old in the world of the Good Documentation Writing, and some will look like obvious common sense. But we are nothing if not animals of education, and it is a hopeful perspective to measure quality by the extent of learning over time, rather than the number of errors :).
With that being said, let’s dive in.
Create a styleguide
The first immediate task was to define a consistent set of rules for writing articles. In this way, users would find the same familiar structure in all answers, and different authors would be able to contribute more easily.
The design of LumApps comes from material design (cool kids say “MDI”), the design system created by Google in 2014.
This is the subtitle of the section writing style:
Text should be understandable by anyone, anywhere, regardless of their culture or language.
The read is fascinating; you will learn how to write better error messages and inviting button labels. While those guidelines were originally written for product development, we wanted to create our knowledge base as if it were a product. Help Scout wrote an enlightening post on this topic, making a case for “clear, concise, digestible content”.
We therefore wrote our own Material Design Knowledge and Instruction Site Handbook We called it the MDI-KISH.
Here is an excerpt. It’s raw and difficult to scan, but useful as a reference for hard decisions. In short:
- Start titles with an action verb (forcing the article to answer a question)
- Use numbered steps only (focusing on the how rather than the why)
- 1 article = 1 use case (both avoiding the “explaining how it works” effect, and restricting to a single action)
- Consistent syntax (optional objective of the action THEN location THEN action)
Using numbered steps only may seem extreme. This was purposeful; we wanted to build help site articles as exact answers to standard questions. Explanations would be handled in blog posts, or tutorials.
Also, the “1 article = 1 use case” rule led us to create many different — but similar — articles. This is something we changed in version 3, but at the time we thought people wanted the answer to their question without having to scroll through a page (spoilers: it’s not that simple).
Refine the target
Some actions in LumApps can only be done by administrators, some by a group of users, some by everyone. We decided to write everything on the assumption that the user had total permissions on everything.
One of the reasons to exclude end users was that LumApps applies to large businesses environments, and there tends to be several organizational layers of support between the end user and the product help site.
Some years ago, I trained users on Gmail, which safely qualifies as one of the easiest application to use. Email has been around for decades so the concept is familiar, and the Gmail interface is lean and clutterless. Yet I observed that only a small amount of users looked for answers online, let alone on the Gmail support site. They would rather ask the people identified as more knowledgeable around them, creating a pyramid of support where only the experts would think of searching on the product help site.
This meant that we were taking the path of internal support, away from external support. It would only serve the needs of the LumApps support team, project managers, presales engineers, and partners — all of whom had enough autonomy and interest to search by themselves. That was a conscious choice: we wouldn’t scale without helping ourselves first.
Document with a purpose
One of my favorite sociology articles is called L’opinion publique n’existe pas (in French), written by Pierre Bourdieu in 1972. He explains in an eloquent way how asking questions in public surveys can influence answers, and even opinions. The point being that questions aren’t neutral.
Our goal wasn’t only to answer questions, but also generate ideas, and suggest articles based on what you had already read.
A “related articles” section is a typical way of achieving that. If you want to add an image, maybe you’d be interested in knowing how to add a video. We added that section on the right-hand side of all articles.
Our second idea was to write a general tutorial on how to create a full LumApps site from scratch — we called it “Getting started”. When you have just installed LumApps, you’d be able to learn, step by step, how to use all our features. At the end of each chapter, you would have a usable site, but incrementally refined with more features and use cases. This image of learning as a tree rather than a flat space was inspired by Sizhao Yang’s tweet (I encourage to read his whole thread on the subject).
The term purposeful documentation wasn’t in our mind by then, but it sums up nicely what we were reaching for.
Embrace complexity, avoid confusion
LumApps is a complex application; one cannot just install it and make it work without learning its key concepts.
It is a mistake to think that complicated questions require complicated answers. Each article would describe a single action, in less than 10 steps.
Regardless of the product interface complexity, we wanted actions to feel easy to perform, and logical. The LumApps installation article, for instance, has many ramifications of what to do depending on your environment, but we needed to make it feel simple. We rewrote it dozens of time — and it is still far from perfect.
You can always improve a product interface for usability, but everyone should play their part. As a writer of documentation, there is value in taking complexity, and making it look obvious to a user reading your explanations.
Celebrate and improve
We started writing the articles for the new help site in July of 2017. In September, we opened it to partners, and in the middle of October to everyone.
In a number of days, we were using it internally — either for our own knowledge, or by copy-pasting them to answer customers with precious time gain. If nothing else, we had reached the dogfooding stage.
