Rolfe Dlugy-Hegwer
improving, reinventing, and transforming technical communication
Just as wild animals follow patterns that allow them to find adequate nutrition with the minimum expenditure of calories, information seekers follow patterns that allow them to find adequate information with the minimum expenditure of mental energy.
Mark baker, Every Page is Page One
How I create my to-do list in todoist
Recently, I wrote about zero inbox, my hack for getting rid of email stress and mess. I also mentioned that it depends on having a to-do list that can link back to your email messages.
A few years ago, I started using the free version of Todoist, an elegant and dependable app developed by a Germany-based software company. I was so pleased that I upgraded a year or so ago to their Premium version for $3/mo, billed annually.
Getting the most out of my to-do list requires a little skill and effort. Here’s how I add tasks to todoist:
- Using the todoist extension in Chrome, I create an item for (almost) every task I encounter. The extension makes it easy to link to an email message or browser tab that’s open.
- I avoid creating duplicate to-do items for tech docs deliverables I’m already tracking in an enterprise tool, like Jira or Bugzilla. Duplicates double or triple the amount of maintenance work I have to do.
- For tasks I’m already tracking in enterprise tools, I create an umbrella task like “Work on the top priority item in Jira.”
- Because this work is my highest priority, I type “p1” as a keyword in the item’s description: Todoist highlights the task with a red checkbox and moves it to the top of my to-do list.
- I also mention the “every weekday” keyword, so Todoist makes this item a recurring task.
- Finally, I click “Add website as task” so Todoist includes a link to Jira in the to-do item. This helps me reduce the number of open tabs in my browser, so I’m more productive.
Make it SIMPLE
Il semble que la perfection soit atteinte non quand il n’y a plus rien à ajouter, mais quand il n’y a plus rien à retrancher.
…perfection is finally attained not when there is no longer anything to add, but when there is no longer anything to take away…
ANTOINE DE SAINT EXUPERY, Terre des Hommes, 1939
As technical communicators, how do we ensure that our user instantly gets what the topic is about?
Here are the answers to that question, based on my reading of “Simple,” the central chapter of Chip and Dan Heath’s book, Made to Stick.
The good
Making something simple does not mean dumbing it down.
To make our content simple, we must:
- Find the core idea and present it first.
- Use the remaining content to support the core idea.
- Eliminate everything else.
To illustrate this, Made to Stick describes a problem the US Army had a with orders: By the time commanders in the field received the order, it was outdated and the commanders had to choose between ignoring the order or implementing an order that no longer made sense.
To solve this problem, the US Army improved its communication protocols in 1980 by adding a commander’s intent (CI) to each order. The CI is “a crisp plain-talk statement, [to] the top of every order, specifying the plan’s goal, the desired end-state of an operation.” As a result, field commanders could act on the intention of the order, its core idea, despite changing circumstances in the field.
The CI sounds a lot like the DITA shortdesc element writers put at the beginning of their topic, just below the heading.
- For a procedural topic, use the shortdesc to “explain what the task information helps users accomplish, the benefits of the task, or the purpose of the task.”
- For a conceptual topic, use the shortdesc to, “introduce the concept and provide a concise answer to the question ‘What is this?’ and in some cases ‘Why do I care about this?’ If the concept is unfamiliar, you can start with a brief definition.”
I know some of you feel ill when you hear DITA mentioned in tech writing discussions. Even if you’re not using DITA, you can’t deny that it makes sense to give your readers a clear statement of the core idea at the beginning of your topic.
Doing this helps your reader to quickly “sniff” whether this is the information they are seeking so they can decide to read more or continue looking.
The bad
The opposite of identify the core idea and putting it at the top is:
- Burying it somewhere else in the content.
- Presenting multiple competing ideas.
- Including tangential or irrelevant information.
We don’t do these things on purpose. They happen because we are either blind to them or lack the time and energy to revise them out of existence.
The ugly; revising to good
For me, words are like stepping stones that mark a path through a garden of information. When I revise a topic I’m working on, I reread the words and retrace the path I laid out earlier.
As I do this, I notice odd spots:
- If I notice a misplaced stone, I move it to a better better spot or toss it out.
- When I find a gap, I fill it with a stone from somewhere else or I generate a new stone by generating the idea that belongs there.
Usually, these changes create new odd spots in the path. So, with each move or fill, I spend a bit of time working it into place and reworking the surrounding material. I keep doing this, developing my thoughts and moving them around until I feel like I’m done.
Then I come back the next day and see a whole new set of things that are out of place. This is more of a problem with blog posts like this one than with technical content, whose structure is more defined.
The trouble with “eliminating everything else” is that I’m still generating new ideas (stones) when I’m revising. To solve this, I have to force myself to stop creating and focus only on removal. This isn’t easy if I’m attached to interesting by irrelevant ideas in the content. The solution is to save off a copy of the document before I start cutting away the excess. That way, when I finish the current topic, I can review the copy and use the interesting bits to generate new topics.
How to make your ideas stick. Part 1/7: Introduction
This is the first in a series of posts on my journey as a technical writer to improve how I deliver ideas to readers’ minds and make them stick there.
You never know where you’ll discover a gold nugget. I found Chip and Dan Heath’s work by chance in a Google docs slide template called Making Presentations that Stick.
Intrigued, I googled “Chip and Dan Heath” and found their New York Times bestseller, Made to Stick, why some ideas survive and others die.
I was amazed to see that Amazon’s preview of Made to Stick generously gives away the “big secret” at the very heart of the book! It’s right there, free for anyone to read and use!
Most books keep their core ideas hidden away so you have to buy the book. Here, the authors flip that approach on its head. They give away the core idea for free, like open source software. They know these ideas are so simple and useful that they’ll find a much larger audience than if they were hidden. Then, that audience will turn right around, buy the book, and mention it to everyone they know. That’s what I’m doing right here.
The principles of the book boil down to an acronym, SUCCES:
- Simplicity
- Unexpectedness
- Concreteness
- Credibility
- Emotions
- Stories
I know, I know, you might be thinking – “ugh! Yet another business book with a catchy acronym!” But this book is SO much more than that. It’s a deeply researched and thoughtful work. Each principle is explained and demonstrated with a fascinating collection of stories – examples and anti-examples that give weight and depth to each principle. I’m amazed I didn’t hear of this book sooner. I wish I had read it years ago.
This book has had such a profound effect on me that I’m completely reworking the Explain Better talk I proposed to Write the Docs – Portland 2021 last month. I’ll hear back in a couple of weeks whether it was accepted. Even if it isn’t, I’ll hold an unconference on Explain Better.
In the following newsletters, I’ll discuss how I apply each of the SUCCES principles to technical writing.
Overview: Write the Docs, Portland 2020
This year’s WTD conference was online/virtual only. This shift to virtual conferences make them more inclusive and accessible to attendees whose work, personal responsibilities, finances, or other constraints would normally discourage them from participating. Although this conference was well-attended by folks on the West Coast, by my estimate, half of the attendees were from other regions in the US and Canada; and a handful were from other parts of the globe. I enjoyed breaks and mealtimes with my family and sleeping in my own bed.
Day one, Sunday, August 9th was a pre-conference day with two sets of ten breakout sessions.
The writing day sessions were my favorite part of day one: We got to meet members of the doc teams from GitLab, Microsoft, and Mozilla and contribute to their open-source projects. It was interesting to see the similarities and differences in our tools and workflows.
The event hosting platform, hopin.to, worked well. I stubbed my toe on a few potential improvements, but quickly adapted and had no trouble navigating the event site. The sessions were all live hosted on YouTube, which made it easy to pause the live feed, step away, and then return. I couple of times, after taking a quick break, I caught up with the live session by setting the playback speed to 1.25 or 1.5x. If you’re interested, WTD will probably published the recordings from this year’s event in a month or so. If you’re interested, you can also watch these recordings of last year’s conference.
Days two and three featured a series of fascinating speakers on the main stage.
There was also an unconference, where anyone could sign up for a “table” to give brief talks or discuss anything of interest. For example, shown below is the unconference schedule for the first half of day one.
These unconference tables were the best forums to discuss subjects of interest and meet fellow documentarians (the preferred term for everyone involved in this business). I got to meet more than a few of the main speakers to ask questions about their work.
I’ll probably write a few more posts about some of my favorite sessions. If you’re interested, here is a link to the complete three-day conference schedule.
My first (awful) video presentation
Ughh! 8 days for 8 minutes of awful video
A few weeks back, I saw an opportunity to give a presentation to my fellow developers. The dev lead for oVirt put out an RFP for the upcoming oVirt 2020 Online Conference.
Oh, and by the way, please prerecord your presentation so we can upload it to the conference YouTube channel.
Sure! I thought. No problem, I thought. I’ve given many live presentations, recording a video of one should be easy, I thought.
After a week of working on the material, a day of recording, and several hours of editing, the rendered video was eight, almost nine minutes long.
A week of working on the material
My inspired brain-fart was to simplify modular documentation (aka “mod docs”) and provide a set of markdown templates. The purpose of doing this is to make mod docs easier for developers and other upstream contributors. My goal is to fix the problem of documentarians unintentionally driving away upstream contributors by bringing our specialized doc tools (asciidoc) and methods (mod docs) into upstream open-source projects.
The week flew quickly by as I tried to bring subtractive design to mod docs. I kept going off on tangents, developing a cute bento box analogy for mod docs (that I haven’t given up on yet). Every time I sat down to eat the frog, I wandered off to snack on the appetizers and side dishes instead. I had to work through the material, but that always takes more time than you think. In the end, I thought I had a pretty good set of slides. Many of the appetizers and side dishes ended up as hidden slides – something good to keep for another day.
A day of shooting
This was my first screen capture on Linux. I’ve used TechSmith Camtasia on Windows in the past. Searching Software for “screen capture,” I found OBS Studio. It was easy to set up and record the slide presentation with myself as a talking head in the lower right corner. I’ll write a separate post about how to do that.
The hard part was getting over my stage fright, or proceeding in spite of it. My voice box felt tight the whole day. Listening to myself, my voice sounded reedy and uncertain, and I clung to the words on the slides instead of describing my thoughts. Standing at an improvised podium in my bedroom, I resolved to continue recording to the very end, instead of restarting every time I flubbed a line. “Try several times and move on. I’d fix it on the edit,” I thought.
I used Pitivi to edit the handful of clips Pitivi dropped in my home directory. It was fairly easy to cut away my not-so-good takes and slide the better parts together into one somewhat cohesive presentation.
Finally, I clicked the Render button and waited for a few minutes while it created an .ogv file. I also had it render an MP4 file. YouTube accepted the .ogv file, even though it wasn’t listed as one of the supported file types. The .mp4 file was about a third larger than the .ogv file, and it looked sharper on YouTube.
Debrief
It was slow and challenging, but worth persisting. I have wanted to do this for a long time, and am glad I finally pushed through my discomfort with being in front of the camera. I expect I’ll get faster and better with practice. This is a key skill for some of the work I want to do going forward.
Now, I need to start working on a re-shoot or perhaps a voice-over of the original…if I can get my voice box to loosen up.
Well begun (in Git) is half done
Well begun is half done.
~ Aristotle
Inspired by James Clear’s book, Atomic Habits, I’ve started starting tasks before it’s time to do them.
For example, I prepare the Keurig coffee machine before bed each night. I fill the reusable filter with fresh coffee grounds and top up the reservoir with water. As a sign that everything is ready, I put a cup upside down under the spout.
Eight hours later, in the half-dark of the morning, I flip the cup, push two buttons, and out comes the coffee. No fumbling, running the tap or clinking the cups in the kitchen while other folks and dogs are still asleep. Just flip cup+power on+press start. Voila! Coffee made.
Lately, I’ve been applying this practice to my work using git.
Recently, I documented a new product feature. As we approached the release date, we ran into a software problem we could not fix in time. Instead, I documented a workaround for users to complete before they use the new feature.
The workaround consists of an asciidoc assembly file and a handful of module files. To make sure users notice the workaround, I added a couple of cross-references to other topics. I followed the normal process of git pushing these changes to the doc repo (i.e., creating a pull request and having the changes reviewed, merged, and published).
Soon, the team will fix the problem. When we release the software patch, I need to remove the workaround from our docs.
Here’s the part about using git to get well begun. An hour or so after I published the workaround, with the file names and cross-references still fresh in my memory, I did my future work ahead of time:
- Created a working branch in git.
- Deleted the workaround files and cross-references
- Squashed and pushed the commit.
- Created a pull request (PR).
- Put the PR out for review by the team (no changes required).
This pull request means that on the day the software patch is ready, I only need a few minutes to rebase, fix conflicts (none so far), and merge. Voila! Change published.
Developer-contributed content in upstream docs
“No software spec survives first contact with the compiler.”
One of the interesting bits in the project type #1: Team=Both, Code=Up>Down, Docs=Down>Up scenario is when developers write up their feature plans in the upstream repo. Often, these show up in the /doc subdirectory.
- Often, before coding, a developer writes up a description of the new feature they plan to code. They use this document to discuss and negotiate its implementation with other team members.
- When the developer starts coding, code reviews replace the document as the forum of discussion.
- Reading these feature plans and related discussions is like seeing an artist’s preliminary sketches: They represent the intention more than the result.
- Sometimes, these preliminary docs reflect the developer’s concerns more than users’ and customers’ needs. They focus on back-end issues, celebrate accomplishments, and explain decisions.
- These topics tend to focus more on the feature than the user story.
- Toward the end of the project, as the feature approaches release, the developer might add user instructions to these documents.
- Sometimes these plans describe features that didn’t make it into the software, made it in as beta or tech-preview features, or describe features that have been superseded.
In a future post, I’ll write about how to analyze and use these upstream docs to create better customer-facing docs.
Writing and publishing on GitHub
I hope to create an open community around documenting open-source software and practice what I preach: To eat my dog food, as they say. What better way than to create a repo and invite the contributions of other writers?
To be honest, its a bit tough to do this. I believe in “open source.” I promote it, even.
But here I am preparing to put my most ambitious project out there for others to join, and part of me is holding back. Inviting others to join challenges my sense of ownership. To put these feelings in words: Will this end up creating a mess of written-by-committee pablum that serves little purpose? As a writer, I like to revise and craft my work iteratively. How can I do that if I’m fending off the well-intentioned interference of other writers looking over my shoulder?
To overcome this hesitation, I have to re-envision my notions of ownership. Is this “my content?” Is this “my project?” Aside from contributing content, then, I hope to provide the system by which it gets created.
Systems are composed of people, processes, and technology.
This system I’m creating will consist of:
- People: Experienced technical writers and software teams who need to document open-source software.
- Processes: Open source contributions with an agile workflow following the open-source guide.
- Technology:
- a GitHub repo to manage the contribution process
- GitHub pages and maybe Jekyll on GitHub pages for publishing the content
- Git, GitHub markdown and asciidoc for authoring content on your computer
- The Microsoft Style Guide, which is also an open-source document
