Things I wish people told me about writing docs


(Taylor Barnett) #1

From November 2016 until November 2017, one of my main focuses was improving the API documentation at Keen IO. I ended up giving a talk a few months ago at APIStrat about the things I wish I had known before November 2016.

(Sadly, I do not have audio of the talk.)

Some people in the Write the Docs Slack found it an interesting example of what developers (like me) would like to know before diving into writing docs.

Hopefully, others can find it helpful too! Let me know if you have any questions or feedback.


(Einnes) #2
  1. Thing one: there are technical writers, and you should just hire a good one of those instead. Then you can code, they can put your docs together.

  2. Thing two: be nice to the tech writer so they can help you and you can help them.

That’s what the slides say right? =P


(Taylor Barnett) #3

If working at Stoplight has confirmed anything for me, it is that there’s all kinds of people working on API documentation. In some cases, yeah, they should totally hire a technical writer, but there’s also a lot of cases where it makes a little less sense or isn’t possible.

I like writing docs, and I don’t think there’s anything wrong about developers wanting to become better docs writers, right?

You should see my talk from API the Docs in April where I say:

I definitely agree on #2.


(Einnes) #4

I’m listening to your talk now! It’s on in the background while I fix up some stuff