
Notes on Technical Writing - marcuskaz
https://mkaz.blog/misc/notes-on-technical-writing/
======
BossingAround
A lot of technical writers focus on the style of the text. For example, I've
seen tech writers have long discussions (more than 3 hour-long meetings) about
title capitalization in our organization.

I wish tech writers would channel their focus elsewhere:

\- If you haven't got it working, don't document it. Getting information by
talking to SWEs is not enough. Your docs will lack depth and preciseness, and
it will show. A lot.

\- Show fully qualified imports in code samples. If you don't know what that
is, ask SWEs. Given a computer with installed dependencies (such as Maven,
Pip, npm, etc.), even your (grand)mother should be able to follow the docs.

\- Create automated testsuide for your code samples.

\- Mandate that lack of docs be a blocker for a release.

When there are docs written in perfect style and English, yet none of the code
samples works, or when I have to spend 30 minutes finishing the "obvious"
parts of the code to get it to work, that's when I get really frustrated.

The article seems to be deeply focused on the style. I can't remember when I
got frustrated with documentation because the style was bad, or because the
sentences were too long.

~~~
voidhorse
A fair observation. I do think there's some value to concerns over style, but
far too many tech writers give them undue prominence.

I couldn't champion your bulleted points harder. Honestly, if I had a say in
it, any tech writer working on developer documentation should be able to
code/build/perform/use whatever task or api they're documenting _without_ the
help of an engineer. They should be able to read and understand code, and they
should be willing to do so, even more so than the average engineer using some
library code. They should be capable of understanding a library _deeply_ and
synthesizing and summarizing that understanding for users of the library.

Just as tech writers in the medical field need to know quite a bit about
medicine, tech writers in software should be required to know quite a bit
about engineering software. There's plenty that do, but there's also quite a
few that don't--I think it's a side effect of the field's relative youth.

I really wish more writers would code and do exactly the things you mention,
such as implement robust code sample testing, etc.

The ideal technical writer, at least for software engineering documentation,
is a hybrid of a traditional technical writer and a software engineer[^1].

[^1]: This excludes user-facing software documentation, which is essentially a
totally different field than those that deal with writing for developer or
engineer audiences.

~~~
geofft
How does one become a technical writer? I'm a software engineer, and e.g. I
recently applied to Google for both a tech writer position and a software
engineer position, and they interviewed me and offered me a job for the
software engineer role but they gave me a form rejection for the tech writer
role. I worry I'm stuck as a software engineer because that's what's on my
resume.

~~~
gradschool
Writing something substantial and posting it online would help your chances. I
was offered a job as a technical writer partly on that basis. I agree with the
other comment that software development is preferable for the money, but on
the other hand it's easier to switch off from technical writing at the end of
the day or do your own projects after work than it would be if you were
programming all day.

While I'm at it, being a technical writer convinced me that software
engineering and technical writing shouldn't be separate roles, because a lot
of my time spent asking for clarification about things led to software
engineers realizing they shouldn't have done it that way in the first place,
and then changing it. If they had to write about it themselves, the feedback
loop would have been tighter. Making them separate roles and paying technical
writers less money probably started as some business guy's idea of division of
labor.

------
kaycebasques
When I first saw the title I thought to myself, “shit, another random,
possibly misleading post about technical writing?” but on quick review this
seems to be a well-researched overview of the field. If you were to ask a
practicing technical writer to present a summary like this, it wouldn’t differ
much.

If the author is here, I’m curious if they took that definition of technical
writing from my post? [1] To the best of my memory I feel like I came up with
that definition on my own but also wouldn’t be surprised if I subconsciously
took it from somewhere else.

[1]
[https://kayce.basqu.es/blog/metrics/](https://kayce.basqu.es/blog/metrics/)

~~~
marcuskaz
I am here, and I have read several of your posts, thanks for wonderful
resource. So yes, it is quite possible I took the definition from you, I
collected the various notes over time, so I'm not always positive where they
come from.

------
KineticLensman
I always try to understand the readers before writing a word. Why they are
reading. And what they expect to be able to do better as a result of reading,
or what decision they might be making.

If an author can't answer these questions, they will likely write something
that is perceived as irrelevant, wrong, or simply 'meh'. This is especially
true when writing 'technical reports' as opposed to documentation.

~~~
kaycebasques
"Know thy audience" and "know thy audience's purpose" are the cardinal rules
of technical writing, as mentioned in Marcus's post. Often times there are
limits to how much I can know about my audience. In that case it's especially
helpful to put an "Assumptions" or "Intended audience" section at the top of a
doc.

~~~
HenryBemis
+1 on that "thy audience", and the audience is not just the end-users. It is
the 10 extra layers/people that will get to carry an opinion (and whose
opinion matters) by glancing a document for 1min or less.

------
aazaa
> In this time, I’ve read various resources on technical writing and
> documentation. These are my notes, both to help me remember later, but also
> as a tool to help me think about writing now.

and later, in an apparent contradiction ...

> You don’t need to tell the reader what you’re going to tell them. Just tell
> them.

I think this point could be fleshed out better.

Any piece of nonfiction writing, technical or otherwise, that doesn't give me
a clear idea about its content may not pass my filter. I see this the most in
long-form journalism. But it also pops up when authors focus on themselves,
their struggles, and their aspirations in the first couple of paragraphs.

Telling the reader what they're about to read in the first paragraph of a
technical piece is a courtesy. People are busy, and they don't have time to
wade through a bunch of throat-clearing at the start of a piece. They'll just
close the tab and move on.

~~~
voidhorse
This is a good counterpoint. After all, academic journals have abstracts for a
reason--when people need to get something done, a synopsis quickly helps them
make a decision as to whether or not they actually found the appropriate
resource.

It goes both ways. I think this aspect of the craft is a bit more of an art
than a science. At certain points it's appropriate to signal what you're about
to discuss, at others, it's just noise.

In general, anything that functions similarly to an academic abstract is
probably useful (saves the reader from potentially wasting time, gives an
overview of the general subject matter and idea without delving into details,
takes about 1 minute maximum to read).

~~~
HenryBemis
Abstract or "executive summary" is the paragraph right under the title that
does this in everything I wrote for the exact purpose to give someone the
opportunity to see whether this is his/her go-to document for a purpose or
note. I always like to add/read the ToC, that is also a quick read to see if
this doc is what I am/people are looking for.

------
zelly
Most documentation is so bad and so often out-of-date that I can answer my
question faster by reading the source (or tests).

Everything is so extremely verbose. I don't want to read a 7 paragraph essay
about how this or that feature was developed and evolved over time; I just
need a one line hint and maybe an example. Believe it or not, your software is
not special. We've seen something like it before and get the gist already. I
like the style of man pages, where everything is on one page and organized by
the flag, i.e. actual usage (puts a hard limit on meandering bullshittery).

~~~
toyg
_> I like the style of man pages_

You are in the minority, mate. Man pages are walls of text that cover too much
detail in too little space. A lot of them lack examples.

Most people will take a simple task-oriented tutorial over an all-encompassing
man page. That’s something that Microsoft understood very well back in the
‘90s, providing copious amounts of examples and tutorial on top of basic
reference material. It’s part of the reason they saw orders of magnitude more
adoption for their stack.

~~~
nixpulvis
Walls of text are great, just use / and search for what you want. Between that
and command history, I think this is the best way to navigate software.

------
jszymborski
"Don’t tell the reader something is extremely complex; likewise don’t tell the
reader something is simple. The reader will make up their own mind about a
concept being easy or hard."

I think this is great advice, and applied to teaching. I can't tell you the
number of times a professor has said "and then obviously it follows that" or
"it's easy to see that". Nearly every time that was uttered in a lecture I
wanted to hurl my textbook at the board.

Looking for alternatives? "Is it easy?" or "It might be obvious" work fine.
Maybe use those moments as opportunities to check in with your audience. In
the written context, maybe offer end/footnotes explaining why it might be
obvious/easy.

~~~
combatentropy
Related: don't say someting is interesting. For example, "It's interesting
that . . . " I see this preface more often than "simple" or "complex." Also
there is a type of person for whom your introduction will come across as a
dare to find it uninteresting.

------
kwiens
This is well done!

> Support error recognition and recovery.

I totally agree with this. You have to teach critical concepts a couple
different ways in case one gets skimmed over or misunderstood. We rely on
visuals for this--the text should stand independent of the photo / diagram,
and vice versa.

I wrote a handbook on technical writing summing up what we've learned over
many years of writing iFixit repair guides.
[https://help.dozuki.com/Tech_Writing/chapter/0](https://help.dozuki.com/Tech_Writing/chapter/0)

~~~
kaycebasques
Another hugely important reason to support error recovery: this is how many
people find documentation. They see an error when using an application (or
writing code) and they copy-paste the error into a search engine. If you
provide that error text verbatim in your documentation, you will capture that
search engine traffic.

------
TheOtherHobbes
Tech Writing is a waterfall job.

What's needed is something more like peer review, where the "tech writer's"
job is to ask hard question from the user POV during development - for varying
values of "user", which would include customer, API consumer, and so on.

This wouldn't be code review, because it's about features, interfaces, and
expected behaviours, not the fine details of implementation. And it wouldn't
be a PM job, because it would be peer feedback in the form of dialog, not
management in the form of requirements and specs.

And it should be continuous, so the doc base evolves in parallel with the code
base.

And it should not be an afterthought.

This job does not exist yet. And it should, because virtually all orgs have a
problem where individual developers become repositories of The Important
Knowledge. If they leave it becomes hard to characterise system behaviours and
architectures well enough to understand how they work well enough to
replace/improve/reverse engineer them.

So IMO there's a niche for people who are competent developers, competent
listeners, and competent communicators, who can pull it all together, stay on
top of changes, and leave a readable record of the current state of
institutional knowledge about projects, practices, stacks, and interfaces.

------
tracer4201
I worked on designing and implementing a data architecture at a FAANG. One of
the things we found worked well was bringing documentation as close as
possible to source - that way, making changes to one but not the other has a
high rate of getting caught during code reviews and documentation stays in
sync. The challenge with this approach was then accessibility for non
technical customers who don’t care for nor have reason to look at source.
Instead of building documentation pages, we leveraged a system that was a
registry of datasets, individual columns, use cases, and sample queries... it
was tricky to get right but we implemented a pipeline where documentation from
code would get propagated to this system automagically.

In terms of general technical writing, style is less of a concern I have. The
real challenge is writing efficiently to convey sufficient information to the
audience, without staying too high level but also not providing too many
details. I often suffer from writers blockz

------
timogoosen101
Anyone know where I can get legit technical writing gigs? I used to get paid
to write about Elasticsearch for a company's blog and that was pretty cool.
Would be keen to do something like that again. I can write about anything in
the sysadmin/devops space or in the penetration testing space. Thanks

~~~
BossingAround
Apply to a large company. Google, Microsoft, Apple, Amazon, all of these and
_many_ more have tech writers as a full time position.

Of course, there are not gigs. I know nothing of gigs to be honest.

~~~
timogoosen101
Thanks, but I don't know if I'd wanna do this full time.

------
wilg
I actually found this article a bit confusing to read. I suppose they are
"notes" but I found myself having to reread stuff a few times and it wasn't
organized in a particularly clear way.

Here are some notes I had:

This is a very weird sentence:

> In the 1980s, they developed a minimalist approach and created a wonderful
> Operator Training Manual for the IBM Displaywriter, imagine having to
> introduce someone to using a word processor for the first time.

There is also a misspelling in "the four principals of minimalist
instruction".

In that same section it is confusing to bullet point the four principles but
include a summary of the principle at the end of the bullet point. This makes
it hard to skim. (It's also self-referential, which the previous section
recommends against.)

~~~
justboxing
You will do really well as a proof-reader.

------
all_factz
I’m a software engineer, but I have a degree in English lit. I find I love
technical writing. Maybe it’s because I’m often writing about systems I built,
so I understand them well and the writing comes fluidly — it might be less fun
to write about systems I don’t know as well. Still, I find technical writing
one of the parts of my job I most look forward to: presenting to my colleagues
a proposed implementation, for example, is both a social aspect of engineering
and a way to make sure your design is comprehensible and hence simple
(simplicity being a hallmark of good design). I tend not to stress too much
over whether I’m writing well: the goal is just to communicate ideas, after
all, not to make art.

------
stygiansonic
At the end of this article the author links to and mentions the four types of
technical documentation:
[https://www.divio.com/blog/documentation/](https://www.divio.com/blog/documentation/)

I’ve found this to be especially useful when writing documentation. If you
don’t think in this way them your documentation may end up being an impromptu
blend of more than one type, and hence may not be useful for a specific use
case. Instead I try to structure the documentation for one of these.

------
ChrisMarshallNY
These are great notes!

I’ve been writing for years, but I am constantly finding out that I still have
a long way to go.

Thanks!

~~~
D-Coder
I recommend _Technical Editing: The Practical Guide For Editors And Writers_,
[https://www.amazon.com/Technical-Editing-Practical-
Editors-H...](https://www.amazon.com/Technical-Editing-Practical-Editors-
Hewlett-Packard/dp/0201563568)

~~~
ChrisMarshallNY
Thanks! I'll give it a look-see.

------
criddell
The third section advises to avoid meta writing. So... get rid of the first
two paragraphs of this article?

~~~
leksak
Avoid meta writing when doing technical writing, not when writing about
technical writing. It's already meta.

