I'd Rather Be Writing Podcast Feed

Principles in Tim Ferriss' book The 4-Hour Work Week can be applied to tech comm projects. By focusing on the 20% of tasks that result in 80% of the results, limiting your focus to two mission critical tasks a day, empowering those around you to make decisions, and avoiding distractions from trivial tasks, meetings, and email, you can be much more productive in your work. More than crossing off a list of tasks, this approach will likely make your efforts matter.

Listen to this post: You can download the MP3 file, subscribe in iTunes, or listen with Stitcher. You can watch the Transforming Your Documentation Process presentation here: The panelists were Leon Barnard (@leonbarnard), Zach Corleissen (@zachorsarah), Ted Hudek (@tedhudek), and John Bulava (@jbulava). (It’s funny that WTD lists the Twitter handle for each participant – in reality they should list the slack handle of the person on the WTD Slack channel.) Riona started the panel by posing the problem that started her documentation transformation journey at Google. In internal tech surveys at Google, employees noted that documentation was hard to find. When you did find it, it was often incomplete or inaccurate. As a result, you didn’t know if you could trust the documentation (it might be outdated). Riona said the survey’s findings closely paralleled those from the 2016 Developer Survey on Stack Overflow, which found that poor documentation was one of the greatest challenges in the workplace: According to the 2016 Developer Survey on Stack Overflow, the second greatest challenge in the workplace is poor documentation. 50,000 developers took the survey on Stack Overflow. Even if the sample is biased toward people who are inclined to value good documentation (and hence provide informaton / survey responses on Stack Overflow), it’s hard to dismiss the results about the importance of documentation to developers. As more support for the value of docs, a 2013 survey conducted by Programmableweb (which included about 250 developers) also found that “complete and accurate documentation” was the most important factor in an API: Good documentation is the most important factor in an API (As exciting as it is to find these surveys, don’t get too excited – few people seem to take them seriously, as evidenced by the steady decline or flatlining of employed tech writers. But let’s not dwell on that.) The four panelists Riona chose all moved their documentation process toward openness and collaboration in similar ways: Leon implemented Hugo, a static site generator, along with Swiftype for search. In their new model, customer support agents contribute content directly using text editors and commits. Zach at Rackspace implemented a number of open source tools (which process Markdown) to leverage contributions and involvement with developers. The writers at Rackspace process hundreds of pull requests each month from contributing developers. Ted at Microsoft moved toward another open model involving Markdown with a repository. Anyone can contribute docs, and contributing developers have a lively, quick process that seems to have a tremendous momentum. John at Twitter is moving away from their Drupal environment and looking into Sphinx and other similar processes (though he’s still in the conceptual stage). Twitter apparently gave a seminal talk at last year’s WTD conference that influenced a great many attendees to embrace docs as code. Referring to these transformation trends, Riona said there is “change in the air” – you can feel it in the breeze and on the water. Without question, many writers are moving towards a model that treats doc as code, closing the gap between engineering and tech comm, primarily integrating documentation into Github repositories and other code workflows with engineers. The idea is to put docs in a space developers will look at and feel comfortable interacting in. This enables developers to easily make doc updates themselves and fosters more collaboration and community by having an open contribution process. These visionary writers want to move away from the model where only a few technical writers are allowed editorial access into the inner documentation sanctum. But will treating docs as code achieve these technical writers’ goals? With Riona’s model, she says she’s having success. She looks at code commits and analyzes the number of times developers update the readme file when pushing updates. She finds that deve

At the last Write the Docs conference, Riona Macnamara, a tech writer working on internal developer documentation at Google, moderated a panel about transforming your documentation process. The panel consisted of four writers from various companies -- Balsamiq, Rackspace, Microsoft, and Twitter. The panelists talked about how they increased collaboration and openness in their company's doc culture by transforming their authoring and publishing processes. Most of these transformations involved adopting a 'docs as code' type approach, which seems to be a growing trend.

Listen to this post: You can download the MP3 file, subscribe in iTunes, or listen with Stitcher. You can read the article by Mattias Sander here: Become more productive and motivated. The article originally appeared in the ISTC Communicator (Summer 2016). Sander begins general and describes Lean principles: The idea of Lean is to maximize customer value while minimizing waste, thus creating more value for customers with fewer resources. He explains the main reasons for waste. One of these reasons is “Motion”: Motion is the waste of movement around a product or work-item, for example, reaching too far to grab a tool. These abstract principles about Lean eventually get more specific, focusing on the familiar problem of multi-tasking and context-switching, which turn out to be a sizable drain on efficiency: Task switching could be considered to be Motion. Some estimates say that you lose 40% of your time because of task switching. Here Sander gets into Kanban as a solution to task switching. The basic idea of Kanban is to limit the number of tasks you’re doing at a given time so that you aren’t constantly switching activities and losing the context you need to be productive. With Kaban, you break up your tasks into 3 basic categories: Backlog Doing Done You allow only a limited number of items (for example, 3) in your “Doing” category. Sander explains: The more we have [in our Doing category], the slower we produce because of the task switching. We can use the Kanban method to reduce our work in progress, and to help us keep track of what we need to produce. I’m constantly bombarded with emails, instant messages, social media notifications, and meetings, not to mention having multiple projects I’m working on, so it’s hard to not get swept into the inefficiency of multi-tasking. Sander’s article resonates with a post I read by Joel Spolsky — [Human Task Switches Considered Harmful][http://www.joelonsoftware.com/articles/fog0000000022.html]. Spolsky talks about the inefficiency that occurs specifically when programmers have to switch tasks: The trick here is that when you manage programmers, specifically, task switches take a really, really, really long time. That’s because programming is the kind of task where you have to keep a lot of things in your head at once. The more things you remember at once, the more productive you are at programming. A programmer coding at full throttle is keeping zillions of things in their head at once: everything from names of variables, data structures, important APIs, the names of utility functions that they wrote and call a lot, even the name of the subdirectory where they store their source code. If you send that programmer to Crete for a three week vacation, they will forget it all. The human brain seems to move it out of short-term RAM and swaps it out onto a backup tape where it takes forever to retrieve. Spolsky argues that rebuilding the necessary context to do a complex task like programming is what creates the inefficiency. Consequently, Spolsky says programmers should stick to one task only: As it turns out, if you give somebody two things to work on, you should be grateful if they “starve” one task and only work on one, because they’re going to get more stuff done and finish the average task sooner. In fact, the real lesson from all this is that you should never let people work on more than one thing at once. I currently have two main projects at work, but both could easily occupy my work full-time. In an ideal world, I would simply offload one project onto “someone else.” Since that “someone else” does not exist, I have to figure out how to juggle both projects without the drain in efficiency. Once I get moving in one direction, I find it really hard to put the brakes on and start accelerating in another direction. The time it takes to stop and then restart in the new direction creates the inefficiency, which gets multiplied the more times I stop and start. Assuming it’s not possible

In Become More Productive and Motivated, Mattias Sander provides a well-written overview of Lean, which is a strategy for eliminating waste and focusing more on customer value. What interests me most with Sander's discussion about Lean is context-switching and the subsequent strategy of Kanban, which uses cards to regulate flow. While these principles were developed in the context of Japanese car manufacturers (namely Toyota), they apply equally to the technical writer's world.

Listen to this post: You can download the MP3 file, subscribe in iTunes, or listen with Stitcher. You can read Peter Welch’s essay here: Programming Sucks. Welch starts by responding to criticisms of friends who work in manual labor fields and assume that a programmer’s life consists of sitting calmly at a desk, playing on a computer all day. Welch’s main argument is that programming can be just as hellish as the worst manual labor job, but the hell isn’t in the physical exhaustion as much as the mental insanity you have to endure. More than anything, Welch’s tone is playful and full of images, turns of phrases, and the raw, blunt honesty that tends to define programming culture. Here’s a passage: Websites that are glorified shopping carts with maybe three dynamic pages are maintained by teams of people around the clock, because the truth is everything is breaking all the time, everywhere, for everyone. Right now someone who works for Facebook is getting tens of thousands of error messages and frantically trying to find the problem before the whole charade collapses. There’s a team at a Google office that hasn’t slept in three days. Somewhere there’s a database programmer surrounded by empty Mountain Dew bottles whose husband thinks she’s dead. And if these people stop, the world burns. Most people don’t even know what sysadmins do, but trust me, if they all took a lunch break at the same time they wouldn’t make it to the deli before you ran out of bullets protecting your canned goods from roving bands of mutants. If you followed my previous blog post, Thoughts on “Documentation Avoidance for Programmers”, this article makes a nice juxtaposition. Why is programming such a hellscape to navigate? Well it doesn’t take a genius to put two and two together: When no one documents anything, you end up with a lot of code that no one understands, and hell’s bells start ringing. Welch explains that despite one’s expertise, no programmer fully understands how even his or her own computer works, and only has a modicum of expertise around a small fraction of the technology he or she needs to know: You are an expert in all these technologies, and that’s a good thing, because that expertise let you spend only six hours figuring out what went wrong, as opposed to losing your job. You now have one extra little fact to tuck away in the millions of little facts you have to memorize because so many of the programs you depend on are written by dicks and idiots. And that’s just in your own chosen field, which represents such a tiny fraction of all the things there are to know in computer science you might as well never have learned anything at all. Not a single living person knows how everything in your five-year-old MacBook actually works. Why do we tell you to turn it off and on again? Because we don’t have the slightest clue what’s wrong with it…. Would good documentation solve the problems that Welch describes in “Programming Sucks”? Only partially. It’s not just that code is undocumented, but that the approaches programmers have to take to solve problems don’t follow straightforward logic. Instead of a precise and principled engineer who writes clear, logical, easy-to-follow code that follows best practices and techniques, programmers are forced into all kinds of crazy scenarios where they have to detour away from good practices to satisfy nutty business requirements. They have to merge disparate systems and tools in new, innovative/insane ways. They have to hack together makeshift, often temporary solutions where none exist because software is due for release and project managers demand working code despite the unworkability of the coding language for the scenario. In short, programming isn’t a clear and logical exercise. It’s an art where someone jerry-rigs a solution that miraculously works though it’s built on a bit of mystery and good luck – until it breaks, and then the programmer moves into all-night figure-it-out modes consuming lots

Yesterday on Write the Docs, someone shared an article titled Programming Sucks, by Peter Welch. More than just a developer monologue, this article seems to hit on universal truths about programming, so much so that the article has been translated into 10 languages and even has a professionally-read audio version on iTunes (which I bought for $2).

Listen to this post: You can download the MP3 file, subscribe in iTunes, or listen with Stitcher. Documentation Avoidance presentation You can view the presentation by Peter Hilton here: Documentation Avoidance for Programmers. Some of the tips are ridiculous (and said tongue-in-cheek). Hilton says you can go on Slack or IRC and ask other programmers what a particular class does (even if you already know), and then just copy their answer and use it for documentation. Peter also mentions tactics like responding to requests for documentation by saying, “It’s on the wiki” (even when you know it’s not). Most likely the users will look in vain and then not really bother you again. If they do come back and say they can’t find it, you can then go write it and send them the link (hoping they don’t look at the timestamp). I can’t imagine any programmer actually carrying out these tactics. I think some of these tactics are delivered to produce a reverse effect: to persuade developers that not writing docs turns out to be more inefficient and problematic than writing them. Some of Hilton’s tips are a bit more practical. He mentions pair programming as a way to transfer knowledge without writing docs. He also mentions getting others, namely technical writers, to create the documentation. (Keep in mind that the docs Hilton refers to here are internal programming docs whose info is intended for other programmers, not end-users consuming released products.) Comparisons to Shakespeare Peter also mentioned some other interesting facts. He compared reading programming to reading Shakespeare. If you lived 500 years ago, reading Shakespeare would have made a lot more sense, since people were familiar with the idioms, language, and themes. But once you lose this context and skip 500 years into the future, reading Shakespeare requires the help of experts. Similarly, with software, although the code may seem clear to the programmer who wrote the code, people change companies rather quickly. Within a few years, half of your team will likely be working elsewhere. Technologies also rapidly evolve. In 5 years, some new programmer will be looking at your legacy code, written in a now-deprecated platform, and like a bleary-eyed high school sophomore who looks at Shakespeare and asks What does this mean? the programmer will also spend endless amounts of time trying to make sense of your code. Developers hate writing documentation What struck me more than anything in this presentation is the developer’s tone and attitude toward writing documentation – to developers, writing docs sucks. Developers hate doing it. They would like to get out of writing documentation at all costs. It is the most mundane, tedious activity they can imagine. This got me thinking about how I interact with developers. Sometimes when I ask a developer question after question about how something works, I feel like I’m “bothering” the developer. I try not to ask too many questions for fear that I’m somehow overstepping my welcome. Last Friday I was instant messaging an engineer for about a half hour with a variety of questions. But then – during my IMs – I thought about how much programmers hate writing documentation, and I realized that actually I was doing this programmer a favor. He and others had coded all kinds of functionality that was either not documented or poorly documented on the wiki. I kept learning about newly added features and wondered whether they were described or explained on the wiki (they weren’t) or even had tickets in the issue tracking system (some didn’t). Instead of seeing myself as a nuisance to the developer with my endless questions, I was helping this developer do the documentation he really should have provided when he coded the feature. I was essentially doing the work he hated to do. In the developer’s mind, it’s like I’m the guy with a shovel who follows a horse and rider to clean up the occasional shit while the developer rides on. Of course my presen

This past week on the Write the Docs forum, there was a bit of discussion around a recent presentation titled Documentation Avoidance for Programmers. In the presentation, Peter Hilton lays out a series of tips on how programmers might get out of writing documentation.

At the May WTD meetup, Neal Kaplan gave a presentation titled Two Great Teams that Work Great Together: Bridging the Gap Between Documentation and Support. This post contains the audio and video recording of the presentation.

We recently hosted a Write the Docs meetup in Redwood City with a couple of excellent presenters. Below is the recording of Neal Kaplan's presentation. I also explain a bit about my new lapel mic and recording process.

(The title is a play on Facebook’s old slogan, “Move fast and break things.”) You can download the MP3 file here. You can follow Ruthie on Twitter here: Ruthie Bendor.

At the May WTD meetup, Neal Kaplan gave a presentation titled “Two great teams that work great together: Bridging the gap between documentation and support”: You can download the MP3 file here and view the slides here. You can learn more about Neal Kaplan at his blog: Customers and Content.

At the meetup, first Neal Kaplan gave a presentation titled “Two great teams that work great together: Bridging the gap between documentation and support”: You can download the MP3 file here and view the slides here. Then Ruthie Bendor, a web engineer, gave a presentation titled “Move Fast And … Document Things? Lessons learned in building documentation culture at a startup”: (The title is a play on Facebook’s old slogan, “Move fast and break things.”) You can download the MP3 file here. Having multiple presentations in a short amount of time gives the meetup more energy and interest. At least one attendee commented that he liked this format because it encouraged people to get more quickly to the point. If you’re in the San Francisco Bay area, definitely join the Write the Docs group (it’s free!) to stay updated about upcoming events. You can also join the WTD Slack group. Our next event is called Solve This! Here’s a description: For this meetup, we will help each other with the challenges that we face at work. Here’s how it we will do this. You add a major challenge that you have to the list here. The list is anonymous. The challenge should be a problem that you haven’t been able to solve yourself. During the meetup, we will go through each of the challenges on the list and share opinions about the best solutions. We’re leaning away from lecture-based formats and trying to do more creative, interactive meetups. I help with event planning, and I’d like to adopt a model more like a club, with people who meet to interact and share (more than listen to presenters). However, we probably won’t get away from the presenter model entirely — the dual presenters and lightning talk events worked well and will likely be a format we repeat in the future. Having said that, tomorrow I’m presenting on Jekyll at the STC-Silicon Valley chapter. I’m giving the same presentation I gave at the STC Summit. Speaking of Jekyll, if you’re looking to learn more about it, Mike Neumegen has recorded more than 20 excellent Jekyll casts. By the way, I wanted to drop a quick note about my latest recording technique. To record Neal and Ruthie, I used the Sennheiser Clipmic, which plugs into the iPhone. It worked really well. I’ve been looking for a lapel mic that I could easily clip onto a presenter. Previously, I had a lapel mic attached to a Zoom H4 recorder, which is too bulky to stick in your pocket. But anyone can put an iPhone in their pocket. I recorded at 44,100 khz, 16-bit. The presenters also recorded their screens using Camtasia Studio. When I synced the audio with the Camtasia recording, the two rates matched perfectly! Sponsor message:Convert CHM manuals into online real content in minutes. Just import your CHM files into ClickHelp to create an online documentation system — hosted, browser-based, searchable, and nice looking! Get your ClickHelp.co trial today and give it a try.

During the May WTD meetup, Ruthie Bendor, a web engineer, gave a presentation titled Move Fast And ... Document Things? Lessons learned in building documentation culture at a startup. This post contains the audio and video recording of her presentation.