Archive for May, 2017

I attended my first Write the Docs conference last week, which was great fun. I did not fall off the stage, so my presentation success criteria was met. People liked hearing about the exciting Land of Ops, so even better. (I can see you reading the web version! Self-hosting is an awesome way to spy on your friends.)

This was my second trip to Portland and, unfortunately, I still didn’t get to see the city. At least I was there more than 18 hours this time. Oddly, the event was in the exact same building, and this time I discovered the amazing dance floor in the main ballroom — almost makes me want to go to a contra dance again. (My knees have registered their objection to this proposal.)

I scheduled my trip to be able to go on the group hike, but sadly by the time it actually came around I concluded that five miles with 1000 foot change in elevation was not going to happen. (Less sadly, that also means I missed the Saturday afternoon hailstorm.) My presentation was better as a result, so it was not wasted. I am very grateful to friends who provided feedback, and let me practice in their not-a-hostel hotel room.

Sunday I attended a half day workshop on Structuring and writing documentation by Heidi Waterhouse. The original plan was for more of a developer audience, but Heidi shifted it a little towards practical techniques for writers, including some history of software packages specifically for technical writing. As a self-taught sometime writer, it was useful to see how folks who do it full time approach the task and what techniques help. We did some exercises (using templates: Doctor Who Mad Libs!) and talked about how to solve a reader’s problem that these days usually involves a single page at the other end of a Google search. (Annoyed people want fast and complete answers, or they are going to move on.)

One of the more personally relevant presentations was from Sam Faktorovich on how his R&D outpost of a big company built an internal docs team that could handle code-level details of their software. They tried several different approaches, and found the best option was to hire strong writers and train them for the technical information necessary.

Of 120 candidates, only two had both development and technical writing skills (and they hired both of them.) The developers who expressed interest in writing in the end didn’t work out, but the general writers who could handle complex topics were very successful. The team also encouraged more people in their area to be technical writers by partnering with a local university and sponsoring tech writing bootcamps.

As a person who would have been in that set of two unicorns, I’m still thinking about how to apply this information to my own career decisions. There are indeed local companies looking for people with both development and writing skills. I’ve talked to a few, although so far it hasn’t worked out (for other reasons.) More often, I bring up the subject about relevant roles by saying I’m interested in applying my full range of skills and not only writing code.

Some people are open to such discussions, but the LinkedIn messages in my inbox suggest many recruiters already have their minds very fixed about what they want. They see all the engineering positions on my resume, so that is what they want to talk about. Which is fine as far as that goes. But the more I highlight non-code things I’ve also done, the more I get “So, do you code?” reactions. I’m concerned that if I become more widely known as “A Writer” that there’s no going back to Engineering. I haven’t sorted that out yet, besides putting more energy towards having as many wide-ranging personal conversations as my introvert self can stand.

There were plenty of other interesting presentations, many of which I’ll need to watch the videos because I was spaced out working on my slides. One particularly relevant for developers is Even Naming This Talk Is Hard. Ruthie BenDor had many fine things to say about why everyone who makes stuff others have to use/read/interact with should pay more attention to naming the parts involved. The names we come up with that make sense in our context may have an entirely different context (or none at all) for your user. That could be merely frustrating and annoying, or it could be Very Very Bad.

There are a few videos I for sure need to watch, because I had to skip out on the last few hours of the conference to head to the airport early. While I had my phone off preparing for my talk, my spouse was bailing water as representatives from our landlord poked at things. Eventually they found the one that stopped the water pouring into the kitchen, but it’s still a mess. And, yes, someone asked if I had a runbook procedure for that.