We write technical documentation: a guide for the layman

Original author: Taylor Barnett
  • Transfer


In the fall of 2016, my colleague and I were commissioned to improve documentation and content in my former company. We spent a year on all kinds of documentation: an API reference, tutorials, tutorials, blog posts. Before that, I had been writing docks for 5 years, but had not officially studied it. But you can’t call me inexperienced: apart from documenting the API for projects and startups, I also taught Python Flask at seminars while studying at the latest courses at the university. But now I had the opportunity to focus only on my favorite business: to help professionals of all levels through technical documentation.

This year I learned a lot from the Write The Docs community, from other API providers, and through trial and error. Last year I shared my experience in the report “What I would like to know about writing documentation” at the conferenceAPI Strategy and Practice in Portland. This article is a review of the knowledge gained.

How do people actually read the documentation?



“A nation shudders at a large piece of text merged,” the photo of The Onion

Do you know this feeling like in the picture? It happens. Maybe not physically, but most likely, people shudder mentally. I was constantly tormented by the idea that people would not read my texts if I did not arrange them in an easily digestible way. Damn it, this can happen even with this article.

In theNeilson Norman Group's gaze research in 2006, 232 users looked at thousands of web pages. It turned out that users usually look at pages using an F-pattern:

  1. “First read horizontally , usually in the upper part of the content area. This is the top element of the F figure. ”
  2. “Then they move a little down the page - and make a second horizontal movement, which usually covers a shorter area than the previous one. This additional element forms the middle element of the figure F. ”
  3. “Finally, users scan the left side of content vertically . Sometimes it is a slow and systematic scan, which is displayed as a solid strip on the heatmap. Sometimes the movement is faster, forming spots on the heat map. This is the last vertical element in figure F. ”



The Nielsen Norman Group's heat maps The

study found some alternative scanning patterns, such as a puff cake pattern, a blotchy map, a markup pattern, a workaround pattern, and a purpose-driven pattern. I strongly recommend that you read the report .

It is important to note that the F-template hinders users , but good content positioning helps prevent F-scanning.

What are the specific implications for documentation?


  • The first two paragraphs should include the most important information.
  • Critically important first 3-5 words
  • Headings, paragraphs and bulleted lists with informative words.
  • Font changes (size, links, bold, etc.) may be necessary to keep the reader’s attention

So how to structure content on a page?


  • Prevent scanning: make sure the reader’s information is highlighted
  • One thought on the paragraph. If there are several, break the paragraph
  • Users miss everything that looks like banners, so be careful with the illustrations.
  • Do not extend the text column too much: optimally 65–90 characters

I learned some of these tips from Kevin Burke’s lecture on “How to write documentation for users who don’t read it”. Kevin supported the Twilio documentation from 2011 to 2014.

In addition, paragraphs have their own specifics. Like the Fusion-text of The Onion , when you read a lot of paragraphs, you can miss the point. Then why use them so often? Let's do an experiment from the Keen IO documentation:

Quickly read this:

Event sets can have almost any name, but there are a few rules: the name should have no more than 64 characters. It must contain only ASCII characters. It cannot be null.

Now quickly read this:

Event sets can have almost any name, but there are several rules:

  • The name should not exceed 64 characters.
  • It must contain only ASCII characters.
  • It cannot be null

In both examples, exactly the same text. This is not Newton's binomial: the second helps to assimilate information better and faster. If the paragraph contains a list of any type, turn it into a bulleted list.

Later we will discuss in more detail the layout of the documentation and navigation through it.

Code examples


What is API documentation without code, right? Code samples are in many of our documents, and users actually read them. But the problem is that they do not always pay attention to the surrounding text.

The context in the example code is important for the success of the developer. Developers love to quickly copy and paste. Here is an example with the Keen IO API:

var client = new Keen({
  projectId: "your_project_id",
  writeKey: "your_write_key"
});
var ticketPurchase = {
  price: 50.00,
  user: {
    id: "020939382",
    age: 28
  },
  artist: {
    id: "19039",
    name: "Tycho"
  }
}
client.addEvent("ticket_purchases", ticketPurchase);

The developer quickly copies and inserts this code. And ...



First, how do they even run the file? Probably, as node file_name.js, but it is not in the code. It could be indicated in the comments above.

Well, they started it and ... ReferenceError: Keen is not defined. :-( Keen client was not initiated, there is no import or require operator in the upper part, and it works only after installing the npm library. The

user has fixed everything and started it again ... Guess ?! Another error! your_project_idAnd are your_write_keymissing.

All this could be done more obvious.

Here is an example from the Twilio documentation, which provides a good context for the end user: A


screenshot from the Twilio Node Helper library documentation

This immediately clarifies how to install the library, embed it in your code, and what needs to be replaced in the sample code before running it.

Kopipast bugs


Since we have a lot of code examples in the documentation, successful copy-paste is a rather important feature. Here are two examples of where this is not observed:

# Скопируйте и вставьте следующую команду
$ gem install rails

Seems pretty innocuous, right? Think again, what happens when you copy and paste it into the command line? You will most likely receive:

bash: command not found: $

Common mistake. Either you want the command to look like on the command line, or you accidentally copy it. I would recommend to give up $. You can also find a way to disable copy-paste of this symbol so that the error does not annoy users.

A more recent example: did you check how easy it is to select the code that the user wants to copy?

Kelsey Hightower struggled to copy the code sample from StackOverflow to the Google Cloud Next presentation.


"Good programmers are copying, great programmers are inserting"

Did he do it on purpose? We will never know. However, this is an illustration of how programmers try to isolate large blocks of text on some documentation sites. Make sure the site’s user interface makes it easy to copy large blocks. You can even break these blocks to explain the fragments separately. So they will become more accessible for copying and understanding.

"That's all!"



“That's it!” The phrase seems rather innocuous out of context, but imagine how certain words like “easy”, “simple”, “trivial” and “easy” are perceived when you have problems are not great! When a person is stuck trying to get the API to work, such a phrase questions his intellect and forces him to ask the question: “So I'm stupid?” It demoralizes.

Oversimplification


Simplification is found everywhere. It is most common among beginners writing documentation. Often, the authors of the documentation are at the same time system developers, so some things seem “easy” to them. But after all, they developed this function, wrote code for it, checked it many, many times, and then wrote documentation. When you do something dozens of times, it is clear that it will be “easy” for you. But what about someone who has never seen a UI or function before?

Empathy


The choice of words really matters. Empathy is the ability to understand and share the feelings of others. When we show empathy, we help not only beginners, but also more advanced users. This helps increase the potential number of users, use cases, customers, and even company revenue.

But when the documentation is written by an expert-developer of a project, it is more difficult to show empathy. Here are some helpful tips that have helped me in the past:

  • Ask less experienced project participants to honestly comment on the documentation.
  • Encourage less experienced project participants to contribute or point out items of documentation that they do not understand.
  • Create an environment where questions are encouraged, including those that may seem “obvious” to experienced project participants — this will help to notice “blind spots”
  • In code-review and CI processes, use linters to guarantee language empathy and friendliness for all users.
  • Finally, ask to comment on the documentation of real users, show them the text and ask if everything is clear

Error messages as a kind of documentation


Usually, users are more likely to see error messages than documentation. As Kate Voss says, “error messages are in fact an opportunity.” I believe that many documentation developers are missing out on this opportunity. There is a place for learning, establishing trusting relationships and user expectations. First of all, you will help people help themselves.

Keith on the site Write The Docs tells a lot of useful information about writing error messages. I learned a lot from past work on API error messages, as well as being on the other side of the barricades, getting error messages from other APIs as a developer.

Kate says good error messages are built on three principles:

  • Modesty
  • Humanity
  • Utility

Modesty


Immediately need to apologize, even if it is not your fault. I also practice this in the support service.

Example:

Sorry, could not connect to ___. Please check the network settings, connect to the available network and try again.

Humanity


Use human-friendly terms, avoid phrases like "exception thrown by the target of the call." When writing code for which many error messages are being invoked, it is easy to stray from clear vocabulary.

Example (Twilio status code 401 error):

{ 
    “code”: 20003,
    “detail”: “Your AccountSid or AuthToken was incorrect.”,
    “message”: “Authenticate”,
    “more_info”: “https://www.twilio.com/docs/errors/20003",
    “status”: 401
}

Utility


If you remember something from these tips, remember the utility. Share information with the user on how to fix the problem.

Example:

Sorry, the image you were trying to upload is too large. Try again with images smaller than 4000px in height and 4000px in width.

How to write error messages


As with any other documentation, first provide important information. This can be done by specifying the object first, then the action. The user is looking for a result, not how to get there. This is useful when users quickly scan error messages.

Bad example:

Click the back button to return to the previous page.

Good example:

To return to the previous page, use the back button.

Documentation Error Messages


I find it very useful when generic API error messages are mentioned in the documentation. So the author of the documentation can clarify the error message without increasing the documentation, while at the same time helping the user to understand why an error occurs.

Twilio publishes a complete catalog of errors and warnings with possible causes and solutions. Using this method, you can make actual error messages shorter, but still useful.

In the case of error 20003 (error status code 401, mentioned earlier), there are many possible reasons that are clearly stated in the catalog.


Source: https://www.twilio.com/docs/api/errors

Stripe does something similar with a detailed description of various error codes.




A source:https://www.twilio.com/docs/api/errors

You can even find your error messages regarding StackOverflow issues. Answer them modestly, humanly and with benefit. Because of SEO, users often get your bug reports on StackOverflow, rather than the actual documentation.

Hint: if someone did not respond modestly, humanly and with benefits, then with a sufficient “reputation” you can edit the answers of StackOverflow.

Word choice


Many words have established mental models. For example, words like “libraries”, SDK, “wrappers” and “clients” are already overloaded and pass by the reader’s attention.

In his lecture, “Even for this lecture, it’s hard to pick a name” in Write The Docs, Ruti Bendor explains why choosing the right words can be so difficult.

We often choose bad words, although we constantly do this when writing text. Like many SDK titles, every word gives the reader a wide range of feelings, ideas and definitions. You may not understand this - and often we make wrong assumptions.

In such a situation, the well-known saying “There are only two difficult tasks in the field of informatics: cache invalidation and inventing names” is more true than ever. The quote is often attributed to Phil Carlton, but today there are many variations of this saying. Sometimes at the end add "... and error per unit." Ruthie considers this a demonstration that software today is largely based on someone else’s code or work.

Why are bad object names (or documentation) saved?


As with oversimplification, we often do not understand that the name is bad. This is what Ruti calls a failure of empathy . It is like saying that the problem of bad words does not concern me, therefore it does not exist.

Hint for the USA: To avoid accidental racism, use the words "prohibited list" and "permitted list" instead of "black" and "white."
(Sources: Andre Stalz and rails / rails / issues / 33677 )

It reminds me of what Ruti calls the novice’s thinking error . It is like saying “This is completely clear to me. I do not understand how someone can not understand this. "

Finally, Ruti mentions a localization error . For example, the word Bing in Chinese means "sick."

According to the 2017 GitHub Open Source Survey :

Almost 25% of developers read and write in English is not "very good." When communicating in the project, use a clear and accessible language for people from non-English speaking countries.

Do you consider this when you use Americanisms and idioms in the documentation? Many of them may be incomprehensible to users.

Hint: I firmly believe that one of the greatest “tricks” to solve these problems is the diversity of the team working on the documentation.

There are still cases where we admit a mistake, but cannot or do not want to correct it, because we ...

  • Tied to her
  • We do not find time
  • Not seeing the importance
  • We do not have an agency to fix it.

You can say or hear: "But this is my child!", "Who removed my candy?" "If we rename, everything will break," "I do not believe that changing this name will affect something important."

You can’t be afraid of refactoring and rewriting when it comes to documentation. How to improve it, if you do not agree with the fact that initially not the best choice was made?

How to choose the right words?


First I recommend to ask a question: what words do your users use? There are different terms in different programmer circles, do not try to use others. This is useful not only for readers, but also for search and SEO.

In the end, everything inevitably comes down to a subjective assessment. However, there are several principles worth considering. Ruthie says bad names are what they can:

  • to embarrass
  • to grieve
  • mislead
  • to confuse
  • to insult

On the other hand, good names:

  • contribute to a sudden clarification ("that's it!")
  • put in context
  • explain
  • light up
  • provide support

I recommend to take these qualities into account when reading the documentation in order to make useful and honest reviews about it.

Choosing the right words is difficult. The magic formula does not exist. All users are different, as are product use cases; what works for some may not work for others. If it were easy, everyone would have much better documentation. As Ruthie says to developers: “Writing programs is an exercise in inventing titles. Get over it. ” And if you are writing documentation for someone else's program, “tell the developer if his names do not hit the target.”
Tags:

Also popular now: