I had the pleasure of joining Tom Johnson in another podcast and one of the topics we touched on was that of so-called best practices. Today, I stumbled across this post in a thread about high-tech job interviews:
On a personal note, it was actually a series of such experiences that convinced me to take my current job in academia.
One of the replies linked to this post: Best practices considered harmfull [sic] which summed it up as “Work out what your best practice is, work out how you can improve yourself.”
Unfortunately, by the time I got to this point in my feed, my blog reflex had been triggered, and here we are.
If we have to find our own best practices, what’s the point of having best practices?
Continue reading “Unqualified best practices are just slogans”
After attending Write the Docs 2018 (Portland, edition) and watching a YouTube video, I’ve got it figured out: How you (i.e. anyone) can create documentation as cool as Twilio’s–a consistent entry in lists of the best API documentation examples.
All you need to do is follow these six steps:
- Think, plan, and work iteratively.
- Infuse user research and analytics into your entire writing process.
- Treat your documentation as a product.
- Do what’s best for your documentation customer.
- Create and support a writing process that enables contributions from outside of the writing team.
- Build the CMS that supports all of the above.
You’ll need to understand that it took them a few years to get to where they are, today. And, it sounds like they’ll keep moving the bar.
But, don’t be discouraged. The sooner you start, the sooner those three to five years will be behind you.
A little background
Twilio’s Kat King opened Write the Docs 2018 in Portland this May, starting the conference off with a strong sense of user testing and research. That always gets my attention at a tech-writing conference. The next session by Jen Lambourne continued by describing how she applied user research on documentation. I’ve been going to tech writing conferences for quite a while and I can’t recall going to one with such a user-research focus.
I’ll make references to these videos, in what follows in case you want to go straight to the source (something I always encourage). The practices they describe, however, are straight out of user-centered-design. You can also see some of my favorite books on the topic for more background.
What’s noteworthy here is that the Twilio team has applied them successfully to their documentation–proving, if nothing else, that documentation works like any other product (and perhaps works best when treated as one).
So, here’s how the steps work:
Continue reading “Yes, YOU can write docs as cool as Twilio’s”
You’ll have to take my word for it (or find it on your own, I’m not trying to hide). I’ve seen where your GitHub account is treated as a developer’s code portfolio, and I think that’s a shame. I treat mine more like a code sandbox where I can go and
Having a portfolio is a good thing for those who want to show off such things; however, after having looked at a few open-source projects, I see more that are on the sandbox end of the spectrum than those on the portfolio end–by a 2:1 margin (I’d guess, I don’t count them).
One project that I’m in the middle of is definitely not anywhere near the portfolio end but it’s exactly where it should be. I’m using it to test out different ideas that, if all goes well, will inform the production version of the project, at which point, I’ll create a new repo that incorporates the best of the various experiments. Until then, it’s going to be where I do what I need to do to figure out what it is I want to do.
If you want to see how I’ve coded for money, you’ll have to look at examples in which I did exactly that. Unfortunately, I don’t have any copies of such work, except for maybe some old code examples I used in some documentation.
If you want to see what I’m tinkering with, feel free to check my GitHub Repo (after you find it).