How I learned to love writing tech documentation and how you can get other people to love it too (including yourself).

A thread.
I’ll do this by laying out misconception that people have about documentation and talk about why it’s not true and how you can fix it and change people’s attitudes.
Misconception 1: Documentation is so hard to write.
Documentation can mean lots of different things. If we’re talking about a 700 page NASA flight manual, then sure, docs can take a long time to write and involve serious resources. That being said...
Docs can also mean “here are the top 5 things you need to know about X” Eg where does it run, how does it start, where are the logs etc.

For the person trying to figure this out at 3am, those 5 - 10 lines are a lifesaver.
But even if you are writing a “flight manual” it’s worth it. Why? Because docs fulfill so many different roles:
Eg they are like mechanized training.
Eg 2 they can act as a checklist to make sure things happen in the right order
Etc.
More on this later.
One other item: tools like Confluence etc make writing docs so easy! Plus, once you learn the keyboard shortcuts it feels like a superpower. Think of when you figured out the #vim basics or first played a PC game with the mouse AND keyboard. It’s that cool!
Misconception 2: Developers never write documentation.

Aka “I asked for documentation and was sent a giant email chain”
Look at a blank piece of paper. Then think: “what should I write here for some people who are not me but who might want to know something about all of this stuff. I know? Plus, I majored in tech, not biz writing!”
That’s what developers go through when you ask them “Hey, can you write me some documentation?” Also, developers are not always the best at Confluence etc b/c it’s not their primary tool.
Now, think about this from a dev perspective: “Oh wow, I was asked to fill out this skeleton form of docs that asks me all the key questions they want to know! This is so easy, done.”
You might occasionally get someone who says: “This feels like more work, why should I do this?”

To which I answer: “You can do this once and never get asked these question again. Or not, and we can keep pestering you with questions every time a new hire joins.”
Misconception 3: nobody ever reads documentation
“Nobody”, “never”, “always” and “everyone” are big words. If you spend 30 minutes writing a doc that ONLY ONE PERSON reads and it saves them several hours of time. You just saved the company potentially thousands of $$$
Another example: it’s the middle of a giant outage and the CEO asks “How the F does this work?” And you can say “Here is a quick recap I wrote a few months ago that you can read while I fix it”. Only one person may read it but it was the right person.
3rd example: I’ve written tons of documentation and at times thought: “Is anybody reading this??” And then one of the devs said “I was in a meeting and someone asked ‘who is going to doc this?’ ‘Easy! Alex! We all read his docs b/c they are great’ “
Moral of the story: write docs. People will read them (even if they don’t tell you).
Misconception 4: We all know it so why write it down.
I once worked at a firm that had a Sunday startup procedure where the ENTIRE tech stack came up in a 15 minute window.
Something broke during my rotation so I thought: “This seems important so let me wrote this down.” and then I showed it to more senior folks...
Everyone said “there are multiple things wrong with this documentation.”
The kicker: they didn’t agree what was wrong! Eg There were different versions of what Step 3 was. For a 10 year old process that everyone “totally knew how it worked.”
In other words, writing things down created a common shared “touchstone” that people can “diff” vs their own mental model. When people realize their mental models don’t align, it’s MAGIC to watch the adjustments happen.
If you liked this thread, here is a meta thread of my other threads:

• • •

Missing some Tweet in this thread? You can try to force a refresh
 

Keep Current with Alex Elliott

Alex Elliott Profile picture

Stay in touch and get notified when new unrolls are available from this author!

Read all threads

This Thread may be Removed Anytime!

PDF

Twitter may remove this content at anytime! Save it as PDF for later use!

Try unrolling a thread yourself!

how to unroll video
  1. Follow @ThreadReaderApp to mention us!

  2. From a Twitter thread mention us with a keyword "unroll"
@threadreaderapp unroll

Practice here first or read more on our help page!

More from @alexpotato

25 Feb
A tale of of the benefits of aligned incentives

aka

"Teaching people to play paintball by taking away their guns.

A thread.
Many years ago, I used to coach college paintball.

If you have no idea what college paintball is, below is a thread I previously put together which you might want to read before you continue.

Back to the story, so there are several very hard parts about coaching college paintball:

1. Paintball is a sport that rewards things that go against human nature
2. Very few people have played organized, well coached paintball prior to playing in college.
Read 17 tweets
24 Dec 20
How to do a "make vs buy" decision when you have zero data.

aka "What running professional paintball tournaments at Disney World taught me".

A thread.
So back in the mid 2000's, I was the General Manager for a professional paintball league called Paintball Sports Promotions (PSP).

To give people a sense of scale, here is a picture of our biggest event in 2006, the World Cup:
Some other numbers:
- 10 fields
- 200 teams
- 3,000 players
- 200+ referees and part time staff
- Estimated 40,000 spectators over the course of a week
- The parking lot on the right was 1 of 3 of the available lots
- Total budget for the event was north of $600K
Read 20 tweets
6 Jul 20
How to build an army of top quality people via Amazon Mechanical Turk. Yes, you read correctly, Mechanical Turk (henceforth referred to as MT).

A thread.
Most people think of MT as "that thing Amazon offers where you have a lot of work that you need humans to do where you pay per task and it works out to be below min wage".

Because they have that mental model they automatically equate MT to "low quality" which is wrong...
What most people don't know is that MT gives you the option to save and rank how the people (aka Turkers) performed when doing your tasks (aka HITs).

You can also offer up HITs to your saved Turker lists as well.

Given the above, I'm going to lay out how to build your army...
Read 11 tweets
9 Jun 20
Back in the early 2000's, I worked for a firm that was responsible for investigating TV Smart Card hacking for a major satellite provider.

Here are some of the highlights of how we tracked and caught some of the hackers.

A thread.
So for those of you not familiar with how satellite TV worked back then here is some background.

- The provider would "beam" a stream of data (e.g. TV channels etc) from a ground station up to a geosynchronous satellite
- Geosynch was important as you target a country/region
- The satellite would then take that data & "beam" it back down to the area below it (b/c geosync)
- Individual subscribers would have both a dish & a decoder box (dbox) since the stream was encrypted
- The decoders would have a Smart Card(SC) that could decrypt the stream
Read 26 tweets
14 Feb 20
So wanted to do a thread on using #bash on the #linux #cli .

Bash often gets ignored in today's cloud centric world but there is a lot of cool stuff you can do just with basic commands, the switches on those commands and piping things together.

To the command line!
So I'm going to start out with some of the more basic commands and some switches that people aren't familiar with and then rapidly get more advanced in both usage and stringing commands together.

Never done this on Twitter before so should be exciting!
Let's start with: ls

# show files in a single column
ls -1

# show files with detail
ls -l

# show files in reverse time order
ls -ltr

# show all hidden files
ls -a

# show files with human readable size and sorted by size
ls -lSh
Read 19 tweets
1 Jan 20
A tweet thread of my tweet threads (we must go deeper!) 😎
What it was like working in anti-spam circa 2002 and not knowing much about regexes, database design or Linux ://twitter.com/alexpotato/status/1208948480867127296?s=21
How traders feel about ssh’ing into a host to debug errors they are having with the trading system https://t.co/lANW5pN1jN
Read 29 tweets

Did Thread Reader help you today?

Support us! We are indie developers!


This site is made by just two indie developers on a laptop doing marketing, support and development! Read more about the story.

Become a Premium Member ($3/month or $30/year) and get exclusive features!

Become Premium

Too expensive? Make a small donation by buying us coffee ($5) or help with server cost ($10)

Donate via Paypal Become our Patreon

Thank you for your support!

Follow Us on Twitter!