Writing Documentation When You Aren't a Technical Writer(blog.stoplight.io)
blog.stoplight.io
Writing Documentation When You Aren't a Technical Writer
https://blog.stoplight.io/writing-documentation-when-you-arent-a-technical-writer-part-one-ef08a09870d1
80 comments
I have been a tech writer, and I would say something similar, that you need to know two things to write well: audience and purpose. The road becomes a lot clearer after that. Rules on writing fill whole books, but most writing would improve tenfold if writers remembered audience and purpose.
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.
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.
>"Know thy audience" is one of those concepts where, the more you think about it, the less you realize you know.
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."
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."
Yes, this is a common dilemma. Some suggestions on how to handle in docs:
* 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.
* 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.
It's easier in documentation/writing because people can skim or just quickly decide that what's there isn't for them.
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.
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.
Agreed, presentations are harder than writing in this respect. Conversely, I think docs are usually more effective than video when it comes technical communication precisely because you can scan them. Generally speaking, it’s just a more flexible mode of communication. Although I’ll add that I do supplement the DevTools tutorials with video versions, because some people prefer to see GUI workflows in action.
This will often be the case, whether for writing technical docs, books, articles or other matter, unless you have a curated or specifically targeted audience. It's one of the occupational hazards of writing.
>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."
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" :)
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" :)
It's not hard if the writer deals with their NIH syndrome and realizes that journalism figured this out like 125 years ago with the inverted pyramid structure.
I guess I don't understand what giving a presentation at the right level for an audience has to do with an inverted pyramid structure of a news story. In any case, it's only some journalism. Mostly straight news in newspapers.
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.
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.
Unless your have required attendance, this phenomenon means you haven’t made it clear beforehand what audience your presentation is intended for.
In my experience a lot of people are very bad at paying attention to what it says about session difficulty in the program. I was on the program committee of a tech conference for a number of years and saw a lot of feedback forms from people who clearly don't understand what words like "introduction" and "deep-dive" (and their numerical equivalents) mean.
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.
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.
> "Know thy audience"
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.
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.
> if you aim to high, they won't admit that they don't understand, and if you aim too low they might get insulted
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.
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.
One thing you can do is state assumed knowledge at the start of your documentation. Then you can provide references to other documents in case the reader doesn't know the prerequisites for the doc.
> The most crucial skill for creating quality documentation is to know your audience
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).
[1](https://mithril.js.org/#getting-started)
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).
[1](https://mithril.js.org/#getting-started)
> I could go on for years about all sorts of interesting tips for improving your writing
Please do! Do you have a blog or something to follow?
Please do! Do you have a blog or something to follow?
I write here and there on my personal site [1].
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.
[1] https://kayce.basqu.es/on/metrics
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.
[1] https://kayce.basqu.es/on/metrics
We adopted a set of formal guidelines [0] for our database docs, based on Google Developer Guide [1], and automated the checks as much as possible with linters [2].
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...
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...
Not to nitpick, but as long as I noticed it I thought I'd share:
> 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.
> 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.
A good reason to avoid i.e. and e.g. is that many people doesn't know the difference.
Thank you for sharing these! I manage our internal documentation and one of the biggest challenges (aside from outdated documentation) is making sure that people write accurate docs. I gave up enforcing strict style, formatting, and word usage guidelines. At this point I'll accept anything in any format, and I just clean it up myself later. But maybe I just haven't been presenting the guidelines in a simple enough way, as you have.
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...
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...
I like your list of blacklisted words!
I wonder how well this works. Word blacklists tend to be very crude tools.
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?
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?
Our docs are on github. We enabled Travis CI checks and all commits are now automatically validated with the default and custom markdownlint rules. If the linter finds errors, the committer receives a warning to Rocket chat with a link to Travis CI status page containing errors as well as suggestions on how to fix them.
"Remember that everything in this guide is a guideline, not a draconian rule."
The context makes it clear that it is future tense which should be avoided when describing system behavior.
The context makes it clear that it is future tense which should be avoided when describing system behavior.
I like the idea of CI to enforce it :) I'm tempted; I wonder what the GP uses for that.
We use Travis CI for checks as well as github and travis webhooks to deliver warnings to specific committers who need to fix the errors in a particular PR. Scheduled Travis CI checks send alerts to the general channel if the master branch starts failing.
Some thoughts on documentation:
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.
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.
> I sometimes encounter libraries which provide weird options or methods for which I never understand their purpose.
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:
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
Submit a bug report - treat documentation like code in that sense. You're probably not the only one confused by this.
Probably the index can be either a JSON number (for indexing arrays) or a string (for indexing objects), so it takes JSON to support both. Maybe the library also allows you to index with other JSON values and stringifies them internally, reducing them to the string case.
Number 1 seems to be a pattern that I see coming out of text books where the author begins the chapter by giving you an anti-pattern or okay solution to a working problem and then through the course of the chapter introduces the reader to a better solution. It's a pattern that I've always found frustrating since rarely would the "incorrect" solution have occurred to me if the author hadn't suggested it.
> Some thoughts on documentation:
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).
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).
Ive been doing developer relations at Google for 4+ yrs now and the points about code snippets in this article are great. Let me add another one though.
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.
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.
I did it the other way around; I wrote the tests within the code snippet (https://news.ycombinator.com/item?id=17837016). I was going to remove them when rendering, but in the end I thought they might actually be helpful and clarify things, so I left the tests within the snippets.
For reference, here is the JS test builder (fairly rough): https://github.com/franciscop/server/blob/master/test/exampl...
For reference, here is the JS test builder (fairly rough): https://github.com/franciscop/server/blob/master/test/exampl...
I had an "oh f_ck" moment around docs in my OSS project: I made a small mistake. I wrote "@include" instead of "@import" in the homepage of a fairly well-polished project, https://picnicss.com/. Now, I don't want to imagine how many developers copy/pasted that snippet into their code, saw that it didn't work and blamed their code a hundred times until they ultimately gave up and left the library or SCSS altogether.
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
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);
That's cool that you've found a way to test the code that's embedded in your docs. Google has infrastructure for inserting code from a GitHub repo into docs [1] but I haven't heard of anyone extracting the code from the docs and testing it.
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.
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" %}
That is very nice idea as well. I didn't consider that, but definitely I could pull tests from the test files and display some parts of that. I wouldn't make the full START_FULL bit, it'd be a bit overkill for my use case/resources (or I'd simplify it to something like <test-case from="1" to="4">).
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!
[1] https://superdom.site/
[2] https://github.com/franciscop/magic-promises
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!
[1] https://superdom.site/
[2] https://github.com/franciscop/magic-promises
Rust has a cool feature where all examples in doc comments are automatically run as part of running the tests of the package (`cargo test`). So when your CI is running tests it's also testing your examples.
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.
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.
I've done this, 100% tested documentation for a complex project, and it was a nightmare to maintain (eventually abandoned).
Maybe it makes sense for simple projects, but for my project it was an utter disaster.
Maybe it makes sense for simple projects, but for my project it was an utter disaster.
It shouldn't be an incredible nightmare as long as your toolchain is set up to handle this. Realm.io's documentation followed the "docs as code" notion of having documentation under revision control[1], but took it a step further -- the docs repo was tested by CircleCI every time you pushed to master, and the tests extracted the Cocoa-based examples and ensured they compiled without error. During the time I was there, they hadn't built an equivalent for the JS and Java examples, but it should certainly have been possible.
[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.)
[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.)
The problem was that all the interesting examples had nontrivial state that couldn't be mocked.
When I'm writing documents for whoever touches a system behind me, I write wiki articles on what the system is/does, logical data flow diagrams, and a deep dive into whatever it was that I just touched.
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.
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.
I have worked extensively on the documentation for the Defold game engine (see https://www.defold.com/learn/). Here's a few things we've done:
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.
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.
Good instincts on the suggestions feature idea. My startup builds internal documentation software. We built that exact feature and our customers really like it. The problem with most documentation is that it goes out of date. Wrong docs are often more detrimental than no document at all. Allowing readers to flag information that might be wrong, or even suggest an update to merge, helps to harness a team’s collective knowledge to keep documents updated.
As a programmer, when I write documentation I try to make this work profitable for me. First, I open the specifications I had and I try to describe how it was implemented. Often, this means I have to give a look to my code or tests and this makes me identify a bug or a missing test. I try to be concise and to avoid repetitions because big documentations are more expensive to maintain. At the end, I try to imagine the future me who will have completely forgotten this project and will be asked questions by users who will start using it. When I finish a project, I free my mind of all the details.
Where I work, technical writers earn 0.92 of a developer's wage, while a team leader earns 1.4 of a developer's wage. These are calculated from actual contract with our client.
While I'm pretty good with some documentation tools like docutils and graphviz, it makes me wish not to pursue documentation skills too much.
While I'm pretty good with some documentation tools like docutils and graphviz, it makes me wish not to pursue documentation skills too much.
Dishwashers earn a tiny fraction of a developer's wage, I am quite proficient at washing dishes, and yet I have no fear of trapping myself in a career of dishwashing.
I can think of very few non-contrived workplace situations in which being bad at something is an advantage.
I can think of very few non-contrived workplace situations in which being bad at something is an advantage.
That's a poor reason. Learning how to write effective technical documentation is a great skill for anyone in our field. Even a team lead should be able to edit/review technical documentation.
>Users skip over things that look like ads, so be careful how you display images
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.
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.
Same here.
Relevant XKCD:
https://xkcd.com/570/
Relevant XKCD:
https://xkcd.com/570/
The referenced report from Nielsen-Norman is from 2006 and outdated. They published corrections at https://www.nngroup.com/articles/f-shaped-pattern-reading-we...
Author here. I did mention part of this in the blog post:
> 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.
> 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.
It looks like you have a whole section about it, adding a "never mind" at the end? Am I reading it incorrectly?
Overall, disregard for documentation in places I worked in puzzles me. I like to say:
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.
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.
This is a good overview on how to structure a particular page, but what about the structure of overall documentation? I've actually found several good articles about writing articles, but little about organizing many of them.
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.
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.
Technical writers call this "information architecture".
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.
[1] https://everypageispageone.com/the-book/
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.
[1] https://everypageispageone.com/the-book/
Yep, this! Lots of articles about low level writing, not much on the high level. I've always liked the old school documentation layouts when it used to be printed -- programmers guide, function reference, etc. but sometimes it escapes me how to apply that sort of structure to other domains.
Author here. This is a great point! Stay tuned for part 3 or 4 in the series where I cover some of this stuff.
While there are many excellent style guides out there, I personally went with the IBM Style Guide: Conventions for Writers and Editors [0] when I started writing technical manuals and documentation.
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...
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...
Is it just me or the community is just filled with packages that have a single page, or nearly single page doc.
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)
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)
It helped me to blog about technical things to become better at technical writing.
I found that when I was manually updating documentation I could never keep it perfectly in sync with the code. Now in my open source app the documentation is fully automated and generated as a part of the build process. The interactive documentation covers the app's use in a browser, command line, and static documentation is various formats.
This is very closely related to the idea of a single source of truth that good docs built with OpenAPI Specification use, which is what the company I work for is built on top of (https://stoplight.io/). There will almost always be docs you need to update manually though.
There seems to be lots of good quality content on Medium, but it is quite annoying to use - like a quarter or so of the page is taken up by the navigation bar and the stupid "get updates" bar at the bottom, (13 inch monitor) :(
Great articles (there is a part 2 here:
https://blog.stoplight.io/writing-documentation-when-you-are... )
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).
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).
I agree with most of your ideas, and I usually apply them myself. But wanted to ask about graphics and charts, do you use any specific tool? They can be time-consuming to get right and update.
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).
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).
> graphics and charts, do you use any specific tool?
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").
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'm not the original poster, but Mermaid - https://github.com/knsv/mermaid - looks like a decent way to put easy-to-edit graphs in Markdown.
I haven't had a chance to use it yet, but I want to. It's not part of Github Flavored Markdown.
I haven't had a chance to use it yet, but I want to. It's not part of Github Flavored Markdown.
> - an OVERVIEW/INTENT page/paragraph.
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.
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.
>Medium
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?
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?
https://outline.com/UV57G9
Protip just prepend outline.com/ to any web address and it will give you a nice stripped down version.
Protip just prepend outline.com/ to any web address and it will give you a nice stripped down version.
Like it!
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.