What’s Wrong with a Brief Tech Doc?

Brevity is great for a poem, company motto, ad, some other “selling texts”, and school summary of a long novel. But when you are a technical documentation writer, brevity may not be your best friend.

Let me try to explain why.

As a tech writer, I just love really great tech documentation. I make screenshots and save links of perfect guides that not only look nice, but also help me solve my issues. Yes, I am a mere mortal, and I use software and gadgets too. And I need instructions for them. And like any mere mortal, I open the instruction when I get stuck or break something.?

But so frustrated do I feel when I can’t find an answer to MY question in the documentation. Or when the documentation makes me guess what this answer is. (I appear to be good at guessing.) And this is the problem of brief documents.

I see few text and a couple of screenshots. And the little lazy monkey inside my brain is so happy. Why, it doesn’t want to read much too! But I fight this nasty creature and make my more conscious self read this doc to the end just to realize that it says nothing about how I should get what I want, and leaves me even more confused than I was.

The doc is brief. The screenshots are representative. But why do I feel bad about it all??

1. It doesn’t seem to consider that I’m seeing the system for the first time

At the very first glance, the system didn’t seem complicated. So, I decided to try one thing that wasn’t presented in the first two video tutorials. (Actually, none of the further tutorials explained how to do it either.) And of course, I searched for the document that could help me with it.?

The instruction was satisfyingly short. It contained nice, clear images. But while reading it and staring at the screenshots, I realized that I didn’t know the system well enough to understand what button to click and what option to select.?

The doc was so brief that it lacked essential details.

No links to relevant documents that could answer my questions. No glossary. No getting-started guide.?

Hey, I’m a newbie here! Please help me with some basics. Why not?

2. It doesn’t instruct me on how to complete a more intricate task

Again, the doc was brief. The screenshots were nice and clear. But after I finished reading, I realized that I still had a question. Maybe, a too specific one. Maybe, I had to understand how to do what I was puzzled with after reading the doc patiently. I don’t know.

The product documentation had no more articles on the topic I was interested in. So, I navigated back to the form I was working with and tried to guess how to do what I wanted.

I succeeded. By doing harm to my nerves and wasting too much time.?

Maybe, the thing I got stuck with was supposed to be intuitively clear. Then my intuition is really bad, sorry.

3. It doesn’t tell me what to do if I have issues that block my work

Wow, I can record a video right from the system, instead of creating it in some external program and uploading here. Cool! Let’s try it!

What? Black screen. No sound? Where are the settings? No settings? What’s going on?

Let me check the documentation.?

Alright, no document on that. Oh, there is a brief doc on some video captures. But I don’t need that.

I believe you can feel me now. It was painful. I was really upset. I gave up searching for the settings that still may exist somewhere inside this system. And I will use my OBS Studio to record the video. But… You know. This thorny feeling. It just comes back every time I open the Add video option.

The good thing is that you can attach videos directly from YouTube. That’s cool.

4. It seems to be out of user journey context

I was scrolling through their knowledge base and I couldn’t figure out how they structured it. As I’ve said, there was no getting-started guide, neither any advanced section or FAQ. There were just different categories, named seemingly without any particular logic. Those categories contained lists of docs, mostly how-tos. But those didn’t look consistent or sequent.

Generally, the structure was brief and quite navigable. All docs I opened were brief. But I couldn’t understand where I should go to find what I really wanted to know.

Maybe, they are developing their knowledge base now, so its structure doesn’t seem complete and doesn’t describe everything that I face when working with their system.?

Again, I don’t know. I just know that I couldn’t find any answer to the questions I had. And that’s not cool.

All these issues don’t make their software worse. It is still good at serving its purpose. And I will use it despite the fact that I don’t like the documentation. And I am sure I will get better at understanding all the details even without detailed docs. All in all, I am a tech writer at the IT company. I know the thing.

I don’t want to name the software that inspired me to write this post. And please understand me correctly: it’s just my humble opinion. I do not criticize the authors of the documentation. The issues I faced with it just made me muse over my own job. Do I do it professionally enough to discuss how others do it? I know that I am too far from perfection.

To wrap it up with something positive and life-asseting, I’d like to come up with the solutions which I would try to implement to improve user experience with tech documentation.

So, here we go.

My humble solutions

1. Remember that your document may be opened by a user who has been working with your software for just ten minutes. Make sure you can help them navigate to some getting-started thing, glossary, or FAQ, if you have them. If not, give this user enough links to read more about the things they don’t know yet.

Some say that redundant linking is not good. I would say it depends.

What I do in case I feel I must provide many links is a separate chapter in the document, like “More Information” or “References”. It may work.

2. Be specific. Try to walk the user journey in the user’s shoes and think what questions they may ask while working with a form, table, dashboard, etc. (the user, not shoes). Even if you realize you may go into much detail, provide these details. Unless it is a technical know-how that the user doesn’t need to know.

Create advanced instructions for advanced or too curious users.?Explain as much as you can. And I tell you that even in this case, the user will still have question. As tech writers, we must provide them with enough information to help them find the answer themselves.

3. Write FAQ. Create a live chat. Organize convenient communication with the support team. Do anything that could help the user who can’t succeed in completing their task.?

I couldn’t record the video not because I was in a hurry and didn’t want to figure out how to do it. I know such type of users. They say they don’t have time to learn although they have great resources to do it. Well, lack of time is your problem, dear. Not the problem of the tech writer, developer, or project manager. If you really need to make something out, you will find time to do it.

Anyway, I couldn’t record the video because there may be a gap in the functionality. And because there was NO document on how to do it. And there was NO point of contact to reach to and get help from.

I am sure that with the help of even a brief doc I could handle the recording.

4. Structure your knowledge base and every single document well.

The knowledge base can’t be a collection of random categories with lists of randomly organized docs. The doc can't describe everything randomly, without any logic in the sequence of the headings.

With the structure, you build and manage the journey of your user through your product – from the basics through the most essential features to the advanced configurations and relations. Make this journey as easy as possible. Though I perfectly understand that it’s not always possible. Let’s try our best.

These solutions aren’t a panacea. Welcome to suggest more effective ones. Welcome to comment and share your opinion.?

We are here to help each other become better experts and more confident users. Every day we switch from one camp to another, depending on whether we develop software (or whatever) or use it.

Thank you!