
Writing Documentation When You Aren't a Technical Writer - pytlesk4
https://blog.stoplight.io/writing-documentation-when-you-arent-a-technical-writer-part-one-ef08a09870d1
======
kaycebasques
I'm a technical writer. I write the docs for Chrome DevTools and Lighthouse.

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.

~~~
ghaff
>"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."

~~~
kaycebasques
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.

~~~
ghaff
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.

~~~
kaycebasques
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.

------
rodionos
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...](https://axibase.com/use-
cases/tutorials/workshop/technical-writing.html#grammar)

[1]:
[https://developers.google.com/style/](https://developers.google.com/style/)

[2]: [https://github.com/axibase/docs-util](https://github.com/axibase/docs-
util)

[3]: [https://axibase.com/use-
cases/tutorials/workshop/technical-w...](https://axibase.com/use-
cases/tutorials/workshop/technical-writing.html#example-names)

~~~
yread
I like your list of blacklisted words!

~~~
avian
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?

~~~
rodionos
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.

------
TheAceOfHearts
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.

~~~
Sean1708
> 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:

    
    
      get :: JSON → JSON → JSON
    
      Get the value at k from the object
    

While I can use common sense to guess at the order, I have absolutely no idea
how you're supposed to index JSON with JSON.

~~~
voltagex_
Submit a bug report - treat documentation like code in that sense. You're
probably not the only one confused by this.

------
habosa
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.

~~~
franciscop
I did it the other way around; I wrote the tests within the code snippet
([https://news.ycombinator.com/item?id=17837016](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...](https://github.com/franciscop/server/blob/master/test/examples.test.js)

------
franciscop
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/](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](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);
    

In the build process, that snippet will be captured, the test extracted and
run. That way, as a one-man dev, I can make sure that my snippets are tested
and working automatically. I've gotten busy since then and haven't had the
chance to refactor the code or test all the examples as I'd love, but many of
those tests are still there, making sure the code examples are working.

~~~
kaycebasques
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.

    
    
        // START_EMBED
        fetch("example.com");
        // END_EMBED
    
        // Boilerplate infrastructure that the user doesn't need to see.
        new Test().run();
    

One advantage of the Google approach is that you write the code once, but can
insert code one line at a time into the doc. For example, suppose you start
off with the full code sample.

    
    
        const service = new Service();    
        service.init();
        service.doStuff();
        service.terminate();
    

But then you want to discuss the first line:

    
    
        const service = new Service();
    

Then the second, and so on. The Google markup looks something like this:

    
    
        // START_FULL
        // START_CONSTRUCTOR
        const service = new Service();    
        // END_CONSTRUCTOR
        // START_INIT
        service.init();
        // END_INIT
        service.doStuff();
        service.terminate();
        // END_FULL
    

And then to embed a certain snippet into each doc you just do something like
this:

    
    
        {% includecode "https://github.com/.../code.js" snippet="FULL" %}
    

[1]
[https://news.ycombinator.com/item?id=17835045](https://news.ycombinator.com/item?id=17835045)

~~~
franciscop
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/](https://superdom.site/)

[2] [https://github.com/franciscop/magic-
promises](https://github.com/franciscop/magic-promises)

------
Multicomp
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.

~~~
sicher
I have worked extensively on the documentation for the Defold game engine (see
[https://www.defold.com/learn/](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.

~~~
andygcook
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.

------
b0rsuk
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.

~~~
dickeytk
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.

~~~
tbarn
Yes! And this is why I wrote the piece. There will always be developer and
engineers writing documentation for projects, why not help them be better at
it?

------
Timpy
>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.

~~~
Kurtz79
Same here.

Relevant XKCD:

[https://xkcd.com/570/](https://xkcd.com/570/)

------
uweschmitt
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...](https://www.nngroup.com/articles/f-shaped-pattern-reading-web-
content/)

~~~
tbarn
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...](https://www.nngroup.com/articles/f-shaped-pattern-reading-web-
> content/)), but good content design can help prevent F-shape scanning.

~~~
rhizome
It looks like you have a whole section about it, adding a "never mind" at the
end? Am I reading it incorrectly?

------
b0rsuk
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.

------
mr_tristan
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.

~~~
kaycebasques
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/](https://everypageispageone.com/the-book/)

------
chaoticmass
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...](https://www.amazon.com/IBM-Style-Guide-Conventions-
Writers/dp/0132101300/)

------
devxpy
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)

------
k__
It helped me to blog about technical things to become better at technical
writing.

------
austincheney
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.

~~~
tbarn
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/](https://stoplight.io/)). There
will almost always be docs you need to update manually though.

------
akudha
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) :(

------
LarryL
Great articles (there is a part 2 here: [https://blog.stoplight.io/writing-
documentation-when-you-are...](https://blog.stoplight.io/writing-
documentation-when-you-arent-a-technical-writer-part-
two-59997587cc2a?source=collection_home---1------0----------------) )

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).

~~~
slx26
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).

~~~
LarryL
> 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").

------
andrepd
>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?

~~~
trishmapow2
[https://outline.com/UV57G9](https://outline.com/UV57G9)

Protip just prepend outline.com/ to any web address and it will give you a
nice stripped down version.

------
DrBazza
Terse and unambiguous. That's it.

~~~
dragonwriter
“Terse and unambiguous” -> “concise”.

------
BelgradePhantom
Like it!

