Writing Documentation When You Aren't a Technical Writer
blog.stoplight.io
blog.stoplight.io
The tips in this article are mostly fine. Nothing controversial there. It has some good advice, but ironically, the article itself doesn't follow its own advice.
> The first two paragraphs must state the most important information.
The most crucial skill for creating quality documentation is to know your audience and then write for that particular audience. What knowledge are they bringing into the doc (and therefore you don't need to cover)? What knowledge are you assuming that they know? What if they don't have that knowledge? Hint: They'll probably find your doc confusing and frustrating. What is their likely emotional state going into a doc? E.g. if you're documenting an error code there's a higher chance that they're panicked, so don't waste their time! Given a particular audience, what exactly is "the most critical information"?
"Know thy audience" is one of those concepts where, the more you think about it, the less you realize you know. It's a lifelong journey. But the more you focus on this concept, the better all of your communication will get.
I could go on for years about all sorts of interesting tips for improving your writing, but it's all a waste of time if you don't have an overarching guiding principle. And that principle is to know and write for your audience.
Please do! Do you have a blog or something to follow?
The intended audience of the few things I’ve written were geared more towards practicing technical writers, but maybe it’s high time to cover the fundamentals.
There’s a mailing list at the bottom of the post I’ve linked to, where you can get a ping whenever I publish a new technical writing post.
And it's doubly hard because the audience is almost always something of a mix. I've given more than one presentation where the survey has included some variant of both "Way too basic" and "Went way over my head."
* Too much information is usually better than too little. You can organize the extra information into separate sections, which makes it easier for the advanced audience to skip over. * Prioritize one audience over the other.
In the case of presentations I'd probably stick to prioritizing one audience over another. Given a room of people, who is it most important to transfer knowledge to? Better to make half the room happy, than none of the room.
There's more of a commitment in a presentation. It helps to advertise things accurately. Although there's no shortage of people who come to an "Introduction to" talk and expect it to be deep in the weeds.
And the motivation was partly practical. Inverted pyramid lets an editor cut a story at a more or less arbitrary point in order to fit it in a hole of particular size on a page. This is/was particularly true of wire service copy.
We tried a lot of different approaches and you still end up with some audience members whose expectations are seriously out of tune with the content of sessions.
Of course, sometimes there's fault with the presenter too.
I once gave Unix and C training (two separate courses) to a group of experienced corporate IT developers (at a large Indian public sector company, Hindustan Aeronautics Limited). When I was explaining some of the finer points of pointers (pun not intended), like star star argv (pointers to pointers etc. - in the C course), one of them said: "now it is overhead transmission" :)
With end users I find it very hard to predict technical knowledge, which can vary by orders of magnitude and often include misinformation or the completely wrong focus, and which users themselves estimate unreliably. For that reason, unless I know better, I tend to aim low - better to tell them extra than to make it incomprehensible.
There seems to be ego tied up in it for users; if you aim to high, they won't admit that they don't understand, and if you aim too low they might get insulted:
I get complaints, often politely implicit, that they feel condescended to. How does one communicate the basics without sounding condescending? I have some sense of it, of course, but I don't feel that I know the trick.
Yes, it's a tricky balance. Another way to frame the importance of this topic is: if you explain too much, you make your readers wade through a flood of information, which slows them down; if you explain too little, the doc is unusable.
> How does one communicate the basics without sounding condescending?
ASinclair's suggesting of adding a prerequisite section to your doc is a good strategy. It also helps to develop "content types" where you describe in general what types of information you include in each type of content. For example, suppose you define 3 content types: overview, tutorial, and reference.
* The overview contains conceptual explanations.
* The references contain everything you might possibly need to know about a given topic.
* The tutorial contains task-based, step-by-step workflows. Rather than explaining concepts in the tutorial, you link them to the overviews. Rather than going into the nitty-gritty about a topic, you link to the reference.
You probably get the idea from here. Each content type contains clearly-defined amounts and types of information. Rather than jamming all the information into a tutorial, you link off to the overview and reference. The people that need more information can follow the links to learn more. The people that don't need it get a straightforward tutorial without extraneous info.
This can be tricky when your audience doesn't have a homogeneous skill level (e.g. people copy-pasting GA snippets don't necessarily know JS, and I've even seen seasoned developers disregard the recommendations to put the scripts at specific places in the document and then proceed to wonder why they're sporadically losing tracking data.
I've gotten some good feedback from structuring documentation in such a way that a section gradually builds up from the basic knowledge into more domain-specific information [1]
The idea is that you can quickly scan `<code>` sections if all you want is to copy-paste blindly or just speed-read code, but you can "zero in" to a section by reading the accompanying paragraph(s). The guide aims to get to the reader's end goal - i.e. "how to use this thing" - by cutting as many details as we can get away with (and then supplementing the nitty-gritty details in the API section).
I also have the API section landing page be a cheat sheet, which serves as a quick references and a gateway to drill down into the relevant API section in case the sought information isn't covered by the respective cheatsheet section. I find that it's helpful to have a slightly longer "laundry list" that has some context than just having a shorter dry list of disjointed API method names in a left nav (though I do provide the dry nav as well for the power users).
Another thing I find problematic in a lot of docs that I try to address is information architecture. Often times, sites just cobble together a bunch of disjointed sections, which doesn't really help someone who doesn't already know the ins-and-outs of your thing. I try to order the menu items by how advanced are the topics they cover (i.e. tutorials first, followed by more nitty-gritty resources, followed by implementation details).
In my opinion, the biggest challenge is to shift mentality from "Oh, I should write about X, and I guess I need to link to it from the menu somewhere" to "what kinds of things would I search for if I was trying to do X/Y/Z, and where would I go to find that information". This exercise can help uncover areas where more linking can help a user understand the relationship between various parts of the system. Another bonus is that it can also help you write more clearly when you have to assume that a user might land in a given section of docs from a link (rather than having the context from the paragraph above).
How do you fumble something so obvious? Selfishness. The poorest writing I've ever come across I have to assume that the writer is not writing primarily for the reader. He's writing for his boss ("My boss told me I have to write documentation. Once I get this done, he'll be off my back."), for his company ("I have to cover every possible shenanigan in this license or my company might get sued"), for his paycheck ("I'm going to pour on euphemisms like maple syrup so the reader can't help but be hynotized into buying our product"), or for his ego ("I'm going to use really big words, fashionable memes, and a chummy style to get people to think I'm smart.").
All of the other sins are microscopic compared to the writing from selfish motive. Most of the other rules fall into place if you remember just this, love thy neighbor as thyself.
The checks cover spelling, markdown formatting, broken links, and grammar/style. For instance, we specifically reject hostnames, domain names, IP addresses, person names, phone numbers unless it's on our Example List[3], which itself is largely based on RFCs.
[0]: https://axibase.com/use-cases/tutorials/workshop/technical-w...
[1]: https://developers.google.com/style/
[2]: https://github.com/axibase/docs-util
[3]: https://axibase.com/use-cases/tutorials/workshop/technical-w...
For example, how often must people actively spend effort working around all the blocked past tense forms? How do you express that something used to work differently in a previous version under these restrictions?
The context makes it clear that it is future tense which should be avoided when describing system behavior.
This book, "Technical Documentation Basics: How to Write That F*ing Manual" was a great jumpstart resource for me, in helping break some bad habits about word tense, case, and that sort of thing. https://www.amazon.com/Technical-Documentation-Basics-essent...
> Replace "i.e." or "e.g." with "for example".
e.g., means "for example" but "i.e." means "that is", sort of a one-to-one correspondence. E.g.,
Many places make cheese, e.g., Wisconsin, but only one makes that perfect, crystalline, salty, slightly umami yellow gold that I love, i.e., Parma.
1. Don't do things in your examples which you consider anti-patterns. A few years back I remember some Angular 1.x docs which showcased certain examples which the authors considered anti-patterns. Why are you surprised that users are doing things the wrong way if you're the one that taught them? If you must provide an anti-pattern examples for the sake of brevity at least note it near the code sample and explain what the correct usage should be.
2. Give examples of what certain features or options could be used for. I sometimes encounter libraries which provide weird options or methods for which I never understand their purpose. If you added the option it means you must've thought of some use-case for it, right? It's pretty useful when you're not familiarized with a domain and you want to build up the knowledge of its use-cases in case you have to deal with related problems later on.
3. If something is deprecated or its usage is discouraged be sure to point users to the proper solution. I've encountered warning blocks on MDN which suggest using a certain API, but when you click through it turns out that it's deprecated and they tell you that you shouldn't use it. Contradictory information is incredibly frustrating.
Complete, syntactically correct sentences that make sense. Paragraphs / sections that have a start and an ending.
Clear, concise and consistent language (part of the "7 Cs of communication that actually works"). Documentation is not a poem-writing contest. Do not substitute pseudo-synonyms (e.g. table, relation, schema), that's inconsistent and confusing.
Explain concepts and define key terms. A glossary tends to be immensely helpful, especially if it links back to detailled explanations of home-grown terms.
And the usual basics, e.g. think about the intended audience (what can you expect them to know, what do they want, then give them that).
I won't name and shame the author because it's just a little personal project, but my favourite example of this is the following bit of documentation:
get :: JSON → JSON → JSON
Get the value at k from the object
Find a way to pull your code snippets from real code.
What I mean is, write the code snippets somewhere that you can use a your normal coding tools and make sure they all compile. Publish this repository of snippets on GitHub or similar. In your doc system, have the docs pull the code snippets from the repository at page generation time. This repository should have basic CI to make sure the code and dependencies are valid.
If you write snippets directly in markdown or html, they will eventually be wrong. Even if they start correct, it will be a real pain to update them for v2 of your API. Every team I've ever seen that thought they were the exception to this rule was wrong.
For reference, here is the JS test builder (fairly rough): https://github.com/franciscop/server/blob/master/test/exampl...
But it wasn't until a poor soul opened an issue in Github (which made me feel horrible) that I realized how much responsibility people writing the docs have. So I decided I had a to do something for my next project, and I did. Every snippet of code should be tested, see this as an example: https://serverjs.io/documentation/context/#-options
const mid = ctx => {
expect(ctx.options.port).toBe(3012);
};
/* test */
const res = await run({ port: 3012 }, mid, () => 200).get('/');
expect(res.status).toBe(200);
One thing that you might want to look into is conditionally displaying parts of the code. For example, suppose that for a given doc, you only need to display one line of code. But to get the code runnable, you need to put in some boilerplate. There should be a way to only display the one line of relevant code.
// START_EMBED
fetch("example.com");
// END_EMBED
// Boilerplate infrastructure that the user doesn't need to see.
new Test().run();
const service = new Service();
service.init();
service.doStuff();
service.terminate();
const service = new Service();
// START_FULL
// START_CONSTRUCTOR
const service = new Service();
// END_CONSTRUCTOR
// START_INIT
service.init();
// END_INIT
service.doStuff();
service.terminate();
// END_FULL
{% includecode "https://github.com/.../code.js" snippet="FULL" %}
I think it is important where you start a project as well. Many times I will write the docs even before writing any code (totally or partially). If I think the docs and snippets are going somewhere I'll continue with the code. So in a way, it makes more sense for me to pull the data like docs -> code -> tests than the other way around. That way I know where I want to go, and then I try to get there. Examples of my projects like this [1] [2].
I'll very likely try it though, so thank you!
Maybe it makes sense for simple projects, but for my project it was an utter disaster.
[1]: "Docs as code" sounds obvious to people at startups, and we did this at RethinkDB and do it where I am now, but it's relatively new to the traditional technical writing world. (I wandered in here from webdev, so it made sense to me right off the bat.)
There's even some built-in magic to make it nicer. Like if the example needs some code to compile but which would otherwise distract from the point of the example, that code can be prefixed with # and will be hidden in the generated docs.
From there, I make a condensed narrated PowerPoint with pretty charts and UI element screesnhots. If I have bonus time, I might even make a basic Chamilo course to cover the application and immediate dependencies and ecosystem.
This all sounds great to write, but I wonder how much of the work actually gets used. The devs that wrote the program often don't bother with documentation (fail fast and fail forward!) so I have at least a small sense that wiki searches etc will surface my material, but I wish there was a better way to track who found what useful or not without them walking up to me and personally commenting on it.
Suggestions to up my documentation after the fact game are welcome.
We use Google tracking on the site. That helps a bit. We have search available on the site and we get the most useful information from how people use the search function. We get clues as to what users are looking for, what terminology they use and I use that to make sure common searches turn out good information.
I added a "Have a suggestion?" button at the bottom of each page. You have to be logged in to see it (because of bots) but it allows you to mark text directly on the page and then report errors and suggestions. We get a lot of feedback through it, much, much, much more than before when we relied on users sending their feedback or stopping by to talk.
While I'm pretty good with some documentation tools like docutils and graphviz, it makes me wish not to pursue documentation skills too much.
I can think of very few non-contrived workplace situations in which being bad at something is an advantage.
Several paragraphs earlier the author writes "Do you know that feeling when The Onion is eerily right?" and I had no idea what they were talking about until I realized they were referring to the picture right next to it. I thought it was an ad.
Relevant XKCD:
> The study also found some alternative scanning patterns such as layer-cake pattern, spotted pattern, marking pattern, bypassing pattern, and commitment pattern.
> It’s important to note that F-pattern is [negative for users](https://www.nngroup.com/articles/f-shaped-pattern-reading-we...), but good content design can help prevent F-shape scanning.
Documentation is memoization for communication.
Training courses and videoconferences are overrated. A guy gets to wear a suit and (usually) point at some slides. I don't see the benefit of being able to ask questions, because people feel intimidated and few questions are asked. And whenever some new employees arrive, you have to redo the whole thing.
To be sure, there's plenty of shitty documentation. But I think it's the problem with the writer not making an effort to put himself into reader's shoes. A technical writer should be eager to clarify, and improve documentation. His goal should be to be understood, not high page output.
I find that most documentation that goes into a wiki, e.g., Confluence, begins and ends life as a plan. It is then surrounded by business process clutter. And then the true gems of reports about performance analysis or other details just get buried.
What would this be even called? Taxonomy? I sometimes wonder if I could convince people to call wikis, google docs, etc, a "library" and we should have a librarian go organize everything. Because it's a little sad how much knowledge just gets lost.
Hierarchical organization is tough. E.g. if you're working on a docs site, and you have a multi-level nav, what's the best way to organize that nav? Same problem with organizing the directories in a company's intranet.
One idea that is influential within the technical writing community is to "treat every page as page one" [1]. Because of Search, you never know how people will first access your docs. So you always structure every page to handle one topic, and only one topic, thoroughly. And then link profusely to other docs that the user might be interested in.
It is so comprehensive that the book ends up describing itself exactly, as if it were some kind of meta manual.
[0]: https://www.amazon.com/IBM-Style-Guide-Conventions-Writers/d...
Please don't do this. Documentation isn't an rfc. It's meant to be a _content first_ WEBSITE!
- plain html with little styling. Use the standard documentation themes if possible ( like read the docs )
- lots of cross references. Each class/func should be referenced back to it's API. (Sphinx is really good for this)
The article is about API documentation, but the points apply to every documentation.
I think however that a few things are missing in the articles:
1- an OVERVIEW/INTENT page/paragraph.
This is THE thing that is missing in almost every -if not all- documentation I've ever read.
An example that I always use to illustrate the point: the "File" API. In EVERY documentation I've ever seen, the usage of each function/method is detailled, but NOT why some function must be used before others (opening a file is NOT an obvious concept); the concepts (what is a file?), the workflow are NEVER explained.
And Files are basic stuff, what about GUIs? Ever used a big GUI toolset? It's miserable! They never include the high level stuff, you have to dig a lot and if you are lucky, maybe you'll find a blog womewhere that gives a few insights in the mind of the creators. IF you are lucky. So you end up using the wrong type of widget or function (because they look alike) until you crash & burn and realize that it was the wrong choice for your purpose, because NOTHING is explained, you have to discover everything at your cost.
2- graphics/workflow charts
This is related to my first point. When I write documentation I include -at least- one high level graphic that shows how the various parts of the system interact, sometimes a flowchart or a Finite-state diagram (when a FSM is used, obviously).
-----
When I give a module to my coworkers (be they testers or users of my API), I give them that additional documentation which makes it MUCH easier to understand and test/use. What I find stunning is that I'm always the ONLY ONE to do so! At most my coworkers will write _some_ documentation to explain a few difficult points, but it will mostly be comments, not documentation for an user of their API/module. And if you point it out, the reaction will range from "I've no interest in that" to "it's not necessary, the code talks for itself"... To them, the -automatically generated- JavaDoc comments are "enough", which is total B.S.
The most infuriating is that all this -undocumented- code is always the result of a HUGE amount of work and dedication. But it is invariably cruely hobbled by that missing step: helping the users use it properly. I see it everyday in Free/Open source tools, and I've seen it in every project in the companies I've worked with (except mine of course)...
So you spend lots of time trying to understand how the stupid thing is supposed to work instead of doing your real work.
There is a LONG way before the importance of documentation (and comments) is accepted as what it is: VITAL. Unfortunately, as for testing and security, management not only don't encourage the practice, but they often discourage it (poo-pooing -or worse- such concerns).
Also, I believe a problem here is that on large organizations and codebases many programmers don't really understand themselves the relationships/interactions between systems, or people setting the standards think overviews are hard to standardize, or they think other people think documentation is a pain to write so they try to minimize the work needed to get it "right".
EDIT: came up with a better way to put it: documentation should deal with what a system does, why and where, then how it achieves so in a broad sense, and finally deal with the implementation details (which is the only part we are kinda handling nowadays, as you explained).
Usually, I used Visio, not really by choice but because it was available and sometimes used by other coworkers (usually for the specs flowcharts). There was another tool available, that was used in one of those companies, it was better than Visio, but I don't remember the name, unfortunately, due to a insufficient number of licenses, I could not use it.
When I do such stuff on my Linux box, I use various flowchart/diagram tools like Dia (and another one whose name I forget). I've also experimented with various text-based solution (LaTeX-based & the like), but with mitigated satisfaction: those solutions where too heavy & cumbersome for my use case.
As you wrote, those ARE time consuming and have the usual update problem. But that cost is really offset by the benefit of clarity. When _I_ gave a module to the testers team, I gave them a brief (15 to 20 minutes max) presentation and my documents & usually never heard again from them (except when they found a bug of course), while with the other modules (made by my coworkers), I saw them asking for more information all the time...
> EDIT: came up with a better way to put it: documentation should deal with what a system does, why and where, then how it achieves so in a broad sense, and finally deal with the implementation details (which is the only part we are kinda handling nowadays, as you explained).
You describe _exactly_ the problem. And I've been fighting hard to make that simple idea enter in my coworkers -thick- skulls, but with not much success: they often do acknowledge the problem, but either don't care (disgruntled or not professional) or are too lazy or are overworked and take shortcuts, not realizing that medium and long-term they would in fact GAIN some time... As for the management, I've lost all hope, no amount of discussion can enlight them (they only see "THE CODE").
I haven't had a chance to use it yet, but I want to. It's not part of Github Flavored Markdown.
Yes.
I wrote a little tool ([Rippledoc](http://www.unexpected-vortices.com/sw/rippledoc/index.html)) for processing a docs directory of markdown files into a navigable whole, and recently updated it to be able to use the project README.md (the presumed overview/intent doc) to encourage having that front page be overview/intent.
To make Medium work, we log user data and share it with processors. To use Medium, you must agree to our Privacy Policy, including cookie policy.
Is there another place to read this?
Protip just prepend outline.com/ to any web address and it will give you a nice stripped down version.