I have recently updated my technical writing process with a new technique: using audio recording apps to get over my writer’s block. I use the audio recording app to talk through a technically complex concept – this helps me gain clarity about the topic and makes writing easier. I also use the app to practice for webinars, podcasts, or presentations I give – making audio recordings of the content helps me get used to my own voice and reduces my nervousness. Recently, I came across this article published by Descript that I think might help me take my audio-recording game to the next level. Reposting it here (with permission from Descript) for your reading pleasure:
Overcoming Writer’s Block with Automatic Transcription
If you’re a writer — of books, essays, scripts, blog posts, whatever — you’re familiar with the phenomenon: the blank screen, a looming deadline, and a sinking feeling in your gut that pairs poorly with the jug of coffee you drank earlier.
If you know that rumble all too well: this post is for you. Maybe it’ll help you get out of a rut; at the very least, it’s good for a few minutes of procrastination.
Here’s the core idea: thinking out loud is often less arduous than writing. And it’s now easier than ever to combine the two, thanks to recent advances in speech recognition technology.
Of course, dictation is nothing new — and plenty of writers have taken advantage of it. Carl Sagan’s voluminous output was facilitated by his process of speaking into an audio recorder, to be transcribed later by an assistant (you can listen to some of his dictations in the Library of Congress!) And software like Dragon’s Naturally Speaking has offered automated transcription for people with the patience and budget to pursue it.
But it’s only in the last couple of years that automated transcription has reached a sweet spot — of convenience, affordability and accuracy—that makes it practical to use it more casually. And I’ve found it increasingly useful for generating a sort of proto-first draft: an alternative approach to the painful process of converting the nebulous wisps inside your head into something you can actually work with.
I call this process idea extraction (though these ideas may be more accurately dubbed brain droppings).
Part I: Extraction
Here’s how my process works. Borrow what works for you and forget the rest — and let me know how it goes!
- Pick a voice recorder. Start talking. Try it with a topic you’ve been chewing on for weeks — or when an idea flits your head. Don’t overthink it. Just start blabbing.
- The goal is to tug on as many threads as you come across, and to follow them as far as they go. These threads may lead to meandering tangents— and you may discover new ideas along the way.
- A lot of those new ideas will probably be embarrassingly bad. That’s fine. You’re already talking about the next thing! And unlike with text, your bad ideas aren’t staring you in the face.
- Consider leaving comments to yourself as you go — e.g. “Maybe that’d work for the intro”. These will come in handy later.
- For me, these recordings run anywhere from 20–80 minutes. Sometimes they’re much shorter, in quick succession. Whatever works.
Part II: Transcription
Once I’ve finished recording, it’s time to harness ⚡️The Power of Technology⚡️
A little background: over the last couple of years there’s been an explosion of tools related to automatic speech recognition (ASR) thanks to huge steps forward in the underlying technologies.
Here’s how ASR works: you import your audio into the software, the software uses state-of-the-art machine learning to spit back a text transcript a few minutes later. That transcript won’t be perfect—the robots are currently in the ‘Write drunk’ phase of their careers. But for our purposes that’s fine: you just need it to be accurate enough that you can recognize your ideas.
Once you have your text transcript, your next step is up to you: maybe you’re exporting your transcript as a Word doc and revising from there. Maybe you’re firing up your voice recorder again to dictate a more polished take. Maybe only a few words in your audio journey are worth keeping — but that’s fine too. It probably didn’t cost you much (and good news: the price for this tech will continue to fall in the years ahead).
A few more tips:
- Use a recorder/app that you trust. Losing a recording is painful — and the anxiety of losing another can derail your most exciting creative moments (“I hope this recorder is working. Good, it is… @#*! where was I?”)
- Audio quality matters when it comes to automatic transcription. If your recording has a lot of background noise or you’re speaking far away from the mic, the accuracy is going to drop. Consider using earbuds (better yet: Airpods) so you can worry less about where you’re holding the recorder.
- Find a comfortable space. Eventually you may get used to having people overhear your musings, but it’s a lot easier to let your mind “go for a walk” when you’re comfortable in your environment.
- Speaking of walking: why not go for a stroll? The pains of writing can have just as much to do with being stationary and hunched over. Walking gets your blood flowing — and your ideas too.
- I have a lot of ideas, good and bad, while I’m thinking out loud and playing music at the same time (in my case, guitar — but I suspect it applies more broadly). There’s something about playing the same four-chord song on auto pilot for the thousandth time that keeps my hands busy and leaves my mind free to wander.
The old ways of doing things — whether it’s with a keyboard or pen — still have their advantages. Putting words to a page can force a sort of linear thinking that is otherwise difficult to maintain. And when it comes to editing, it’s no contest: QWERTY or bust.
But for getting those first crucial paragraphs down (and maybe a few keystone ideas to build towards)? Consider talking to yourself. Even if you wind up with a transcript full of nothing but profanity — well, have you ever seen a transcript full of profanity? You could do a lot worse.
A few weeks ago, I was invited as a guest on one of my favorite podcasts: 10-min Tech Comm. Check out my episode about why and how tech writers should work on their technical skills:
PS: Tom Johnson is hosting a poll based on the podcast. Cast your vote here: https://idratherbewriting.com/2018/08/10/how-much-time-devoted-to-learning-tech-is-needed/
As you might know, I recently conducted a webinar about contributing docs to open source projects. In this blog post, I am answering few follow-up questions about the topic.
Vinaya Krishna asks:
How to acquire domain knowledge of these communities? (Since you work in Cockroach Labs, there are people who guided you there. But how did you start working on others? Is it just by browsing their pages? Or did you actually get KT from other fellow members?)
Acquiring domain knowledge of the project depends on the complexity of the project. For beginners, I would recommend that they start by just observing the projects that they are interested in – follow the repository, see which contributions are being made, participate in their communication channels (probably Slack or Gitter), and keep an eye out on the issues list. When you feel confident enough to make your first contribution, start small – pick the easiest issue you can find and get a win under your belt. This will help you get familiar with the process and tools, and then you can move on to handling the technical complexity of the project.
I cannot stress enough the importance of being self-motivated and self-reliant when contributing to open source projects. Remember that the project maintainers are most probably employed full-time elsewhere and are working on the project on their own time. We cannot expect them to handhold us through the project – so make sure to do your homework, try figuring stuff out on your own, and approach them only when absolutely necessary.
More details in the presentation: Contributing docs to open source projects
Can a for-profit organization use Github with their data confidential in it?
As far as I know, yes. So GitHub has two flavors: you can choose your GitHub repository private or public. The repositories that seek contributions are public repositories. But you can make your repositories private to keep your data confidential.
Can you please upload the PPT somewhere so that we can visit the links you had mentioned in the closing slides of PPT?
Yes! Here you go: Contributing docs to open source projects
Update: A helpful reader, Suzanne de Veld, suggested the following projects that accept contributions and other useful links:
- GIMP: https://docs.gimp.org/2.10/en/gimp-contributing.html
- WordPress: https://codex.wordpress.org/Contributing_to_WordPress
I recently attended the Write the Docs 2018 conference in Portland, Oregon. For those of you who don’t know, Write the Docs is a community for everyone who writes tech docs. I have been a part of the Write the Docs Slack community for quite some time now, and I have found immense value from the interactions on the Slack channels. I was excited to meet everyone in person and put faces to names (or Slack handles). And I was not disappointed 🙂
The conference is a four-day event that consists of a hike, the Writing Day, and two action-packed days of scheduled talks, lightning talks, unconferences, reception, social, and the job fair. Not being an outdoorsy person, I skipped the hike and joined the group on Sunday for the Writing Day.
Writing Day is a day meant for conference attendees to contribute to open-source docs projects. This was the day I was most excited about. The entire Docs team at Cockroach Labs had prepped and planned for weeks to set up our project for the Writing Day. During our brainstorming sessions, Rich had excellent suggestions about the types of documentation tasks our contributors could work on. Lauren worked tirelessly to create an incredible style guide to help people edit or write docs for our project. Jesse and I created detailed GitHub issues for tasks we had identified and labeled them with `wtd-writing-day`. And all the preparation paid off.
On the day, we had a full table (that is 6-7 contributors) at any given time. I was impressed by how dedicated our contributors were. While a couple of contributors were already familiar with GitHub and Markdown, most of the contributors had never worked with GitHub/Markdown before. But they were determined to learn the tools and contribute to our docs. They worked through our contributing guide and Getting Started docs and made substantial first contributions. By the end of the day, we had received several contributions and the contributors had successfully learned GitHub/Markdown. It was a win-win!
Takeaways from the talks and unconferences
Since I live-tweeted the talks and unconferences that I attended, you can view my key takeaways from the conference here:
In addition to this blog post, I attempted a vlog as well. Here it is for your viewing pleasure:
Thank you for the response to the Contributing Docs to Open Source Projects webinar! You can help me better prepare for the webinar and make sure that you find it useful and answers your questions by filling in the following survey:
Oh, and if you haven’t registered for the webinar yet, here’s the registration link:
I am back from my very first Write The Docs (WTD) conference in Portland. I represented Cockroach Labs at the Writing Day. We set up our project for open source contributions and the response was amazing! And we were in good company – the other open source Writing Day projects included Kubernetes, Write The Docs, and Netlify. I also met up with Mike Lewis from GitLab and had a productive discussion about their open source contribution process. To summarize, I am pumped up about all things open source docs, and want to share all I learned with you!
Which brings me to an exciting announcement: I am teaming up with Information Developers Foundation to conduct a webinar about “Contributing docs to open source projects”. This is a topic I am passionate about because I have benefited immensely from working with open source projects. But my pet peeve is that while everyone agrees that contributing to open source is a great idea, nobody really talks about how to actually go about it. What is an open source project? How do you get started with one? What do you need to know to make meaningful contributions? What are the things to look out for, or things not to do? I intend to answer all these questions and also walk you through a few open source projects I personally like. So join me on May 19 at 8:30 PM IST to discuss how to contribute to open source projects. Here’s the registration link:
Also, feel free to send in any questions or topic suggestions you might have and I will try to answer them in the webinar:
In April, I had the privilege of sharing with you the day-in-the-life posts from four inspiring technical writers. To wrap up the series, I wanted to do something special. Which is why I made my very first day-in-my-life vlog! Here it is for your viewing pleasure:
Don’t forget to check out the day-in-the-life posts of our amazing guests:
Bart Leahy: Day in the life of a freelance technical writer (who previously worked at NASA and Disney)
Jason Tham: Life of a PhD student in Technical Communication
Swapnil Ogale: Day in the life of a contract technical writer in Australia
Larry Kunz: Day in the life of a technical writing veteran
Special announcement: There will be no post next week because I will be at the Write The Docs conference. However, I am planning to live-tweet the conference. Follow me on Twitter to keep up with the live updates!
The last post in this month’s series of guest posts is by Larry Kunz, a technical writing pro for 39 years! I have been a follower of Larry’s insightful blog for quite some time now, and it is an honor for me to have Larry share his perspective here on my blog. So let’s get to it! Here’s Larry’s post:
I’ve worked in technical writing, and in closely related fields, like project management or marketing, for almost 39 years. Today I’m a Lead Technical Writer at Extreme Networks.
We make and sell equipment for data networks — switches, routers, wireless access points — and the software that controls them. I write the documentation for installing, customizing, and maintaining the physical equipment.
You might’ve heard that technical writing is humdrum, that we do the same work day in and day out. That isn’t my experience.
One of the things I love about working in technical writing, in fact, is that every day is unique. We serve our employers and our customers in so many ways, and we use so many processes and tools, that every day presents new variety.
Let me show you what I mean, by stepping through a day in my life.
Knowing the technology
You might’ve heard that technical writers only need to know the basics of the technologies they work with. That isn’t my experience.
Today I’ll read the design specs for a new product the company hopes to introduce. I’ll read with two purposes in mind: to learn about the product, and to return comments to the designer if anything seems out of whack or is unclear. I might challenge the author to explain the app in terms that a customer would understand — to help me (and the customer I represent) understand how to use the app, not how the app works.
Working on teams
You might’ve heard that technical writing is a solitary profession — that you spend most of the time by yourself. That isn’t my experience.
Today I’ll meet with a software designer to get a big-picture understanding of a new app that customers will use to monitor our equipment. I’ll visit the hardware lab, where one of our test engineers will show me how our new switches are cabled together. In both cases, my colleague will help me gain the understanding I’ll need to describe our products to our customers.
You might’ve heard that technical writers aren’t respected by subject-matter experts, or accepted as colleagues. That isn’t my experience.
Today I’ll meet with three colleagues from Engineering, one from Tech Support, and one from Marketing to discuss a white paper I’m developing. This particular piece was inspired by something a customer wrote on the company’s user forum. It looked so good that I suggested touching it up and publishing it on the company website. But now, questions have arisen about whether its recommendations are in sync with the company’s overall marketing themes. I’m sure we’ll have a lively discussion, with each constituency being heard before I try to lead the group to consensus.
Solving problems creatively
You might’ve heard that technical writing isn’t a creative endeavor. That isn’t my experience.
Today I have to write instructions for mounting switches in a rack, when three different switch models come with three different mounting brackets. Some of the steps will be common to all three models, but some will vary. Making each step clear and not leaving anything out will require cleverness and imagination. It’ll require creativity.
Creativity is the art of solving problems, whether the problem is how to paint the creation of Adam on a curved surface (as it was for Michelangelo) or how to document the best way to mount three switch models with different mounting brackets. Don’t misunderstand: I’m not saying that I have even a tiny fraction of Michelangelo’s genius or talent. But I’m saying that he would recognize the creative process involved in doing the job of a technical writer.
A new day tomorrow
After a day of delving into technical details, of talking – and leading a conversation – with subject-matter experts, of solving problems creatively, I’ll rest up for tomorrow.
Tomorrow’s tasks will be different. I’ll post the final, approved version of a Hardware Configuration Guide. I’ll meet with the team that maintains the Confluence wiki we use to communicate throughout the Tech Pubs organization. Since I hold a senior-level position within my team, I’ll also be helping to rewrite the template our organization uses for documentation plans.
See what I mean? Every day is different. But every day makes use of my technical knowledge, every day has me working on teams, and every day gives me a chance to solve problems creatively.
Is technical writing the life for you?