Technical writing is everywhere. From the user manual for your new smartphone to the safety instructions on a bottle of medication, technical writing is all around us. At its best, it communicates complex technical information in a clear, concise way.
And while technical writing may seem daunting, it’s a skill that most of us could probably try our hand at. After all, we’ve all got something to teach others, whether it’s how to use a new software program, troubleshoot a problem, or assemble a piece of furniture.
For this year’s National Day on Writing, opensource.net heard from five technical writing experts about how they got started and what tools they use.
“Markdown is one of those things that once you know it, you don’t think about the mechanics…But when you’re getting set up, learning all of it really feels insurmountable.”
Author Lauren Maffeo
How did you get started with technical writing?
Most panelists started by joining an Open Source community. Writing our first “how-to” article about using Open Source software was a common gateway to a love of writing.
Chris Hermansen: Generally speaking, I’ve been on the computing side of things, involved with analyzing data that my colleagues collect in the field…It’s difficult from that position to give your expertise back when there are probably lots of people that do that but not any sort of organized, active group. It became a question of how to actually give back…I feel that I’m providing value to the communities out there that use the same Open Source tools that I do.
What tools do you use for your writing?
Writers mentioned a number of Open Source options, including Joplin, Asciidoctor and GNU groff.
Lauren Pritchett: “When I was writing more frequently I liked to write in Atom or something like that in Markdown, then put it in a Markdown-to-HTML converter and plop it into Drupal…I really enjoyed working with LibreOffice because of the ability to create templates, repeat processes, ebooks and cheat sheets…
Lauren Maffeo: All of the Pragmatic Bookshelf authors write their books in Markdown. It’s the bare-bones publishing equivalent of GitHub, where you merge the local version of the draft from your computer and then commit those changes to the main document. It’s a workflow built around developers and technical folks first — almost identical to what you would experience when you’re making commits and pull requests on GitHub (with code.) It’s not intuitive, I much prefer Google Docs, not just for the async collaboration but also for the opportunity to autosave, add real-time feedback and incorporate your editor’s feedback seamlessly…
What advice would you give to someone who wants to get started in technical writing?
One theme from this discussion was don’t overthink it. If you find the topic interesting, others will too.
Lauren Pritchett: Often new authors are timid. They say, ‘Well, you know this has been written about before or everybody already knows this so I don’t need to throw in my two cents.’ But the truth is people don’t know your take on it yet and people spend hours, weeks, months researching a topic…Your take could be the answer to somebody’s problem.
How do you typically start a technical post?
Don Watkins: “If I’m writing about a simple screen recorder, I’ll go on YouTube to look for all of the how-tos to get my head around how other people have talked about it, then try to go from there. That research is really really important.”
Lauren Maffeo: I also start with research – both as a writer but also as a service designer. Service design, in simple terms, means that you’re the advocate for the users in a project. It’s very similar to being a developer advocate. Basically, your job is to identify where there’s friction within a product or service for particular user groups. You also have to identify the right user groups and speak to a range of people within those user groups…
Where to publish
The panel also talked about Technically We Write as a great place to write about writing using Open Source tools. Technically We Write is a website about technical writing, technical editing, web content, usability and anything else that falls under the “technical communication” category. Launched in May 2023, the site welcomes everyone to share an article, and Open Source software writing tools are a great place to start. For example, you might download LibreOffice and write an article about “I tried LibreOffice for the first time, here are three things I learned how to do over a weekend.” Visit ‘how to contribute‘ for more.
Join the OpenSource.net community and share your first article with us! We’re looking for ideas or articles on open knowledge. Click the link to ‘submit a post‘ to get started.
Check out the whole 45-minute conversation on YouTube.
Photo by Jo Szczepanska on Unsplash
One response to “Get started with technical writing”
[…] leverages her expertise to propose a holistic approach. It goes beyond implementing governance and fostering a new culture […]