
Writing Documentation When You Aren't a Technical Writer – Part Two - pytlesk4
https://blog.stoplight.io/writing-documentation-when-you-arent-a-technical-writer-part-two-59997587cc2a
======
kaycebasques
I write the docs for Chrome DevTools and Lighthouse. In the discussion for
part 1 of this series I mentioned that the #1 most critical skill for creating
useful docs is to know your audience. combatentropy expanded on the idea [1]
to include purpose:

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

These articles are fine, they have good tips. But, after 8 years of
professional technical writing, I strongly recommend focusing on knowing your
audience and their purpose. This is a superskill that you can apply to improve
any communication.

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

~~~
pytlesk4
100% agree with knowing your audience and purpose. But you are a technical
writer, so these tips might be obvious. Audience and Purpose could be Part 3?

But for people that don't do technical writing day to day, it can be a little
daunting when you are initially tasked with writing some docs. This is usually
the case at smaller companies where people have to wear multiple hats.

~~~
pfranz
I always start with the audience in any writing. I'm often asked, "write
documentation for your tool" by technical peers and managers and I always have
to push back trying to get more specifics. Am I writing for a non-technical
end-user? Am I writing for a technical person troubleshooting the tool (can I
assume they know yaml or how to use a Terminal)? Am I writing for someone who
may reimplement or heavily modify this tool. Is this intended for reference or
to walk someone through the process for the first time? All of those are
documentation and technical writing, but vary greatly in what details you
include and how you approach it.

In my experience, as a tool writer/maintainer I tend to want to document the
implementation, but nobody cares about that until you leave your job (by then
the documentation may be out of date if you don't maintain it). Most people's
highest priority is a troubleshooting guide (which is difficult with a new
tool) and a very explicit walkthrough for non-technical people (which is
difficult to maintain because dialogs get tweaked and supporting tools can
change).

------
icc97
I've been reading a stark comparison recently, ReasonML vs MDN. I realise this
is unfair as MDN has had much more resources and time and the ReasonML docs
are a straight copy of the OCaml docs, but compare the Reason List.map [0] vs
MDN Array.map [1].

Given that the Reason docs are taken from OCaml and modified , I was wondering
how well it would work to take the MDN docs and modify the relevant subset for
Reason.

[0]:
[https://reasonml.github.io/api/List.html#VALmap](https://reasonml.github.io/api/List.html#VALmap)

[1]: [https://developer.mozilla.org/en-
US/docs/Web/JavaScript/Refe...](https://developer.mozilla.org/en-
US/docs/Web/JavaScript/Reference/Global_Objects/Array/map)

------
C7H8N4O2
Does any one else find the site design frustrating? Constant top/bottom bars
and a full window height of low-quality content before the article begins.

~~~
Kagerjay
I always wonder what people are talking about, but I've had this extension for
so long that I forgot how bad medium is.

"Make medium readable again"

[https://chrome.google.com/webstore/detail/make-medium-
readab...](https://chrome.google.com/webstore/detail/make-medium-readable-
agai/kljjfejkagofbgklifblndjelgabcmig?hl=en)

------
chrisweekly
Nice set of guidelines. Mostly "common sense" but given how (un)common that
can be, this is likely pretty helpful for its intended audience. :)

