Technical Writing

Photo by Brett Jordan at Pexels. In the Write the Docs Slack community, folks often ask how to go about deciding what documentation tool or set of tools is the right one to use. I have taken to replying often with a series of questions, instead of answering. Why the Socratic method? Because tooling for docs is a very, very circumstance-specific choice. No one answer is correct. As I have often said in Write the Docs and elsewhere, I firmly believe that a good technical writer can create great docs with pretty much any toolset. Yes, even Microsoft Word, though we might shudder while doing so. ...

Photo by Startup Stock Photos from Pexels. Curious about what a technical writer can do for you? Here are twenty-five things you might find a technical writer doing in their job on any given day: Interviewing a subject matter expert to learn more about what they are writing about. This might be a product manager, project lead, developer, customer, salesperson, developer advocate, end user, nearly anyone who might touch or use what we are a writing about. ...

Photo by Samson Katt on Pexels. Good docs have (at least) six key characteristics: Findable For documentation to be worth the time spent creating it, the user needs to be able to get to those docs when a problem or curiosity creates a need for information. The best docs do nobody any good if they can’t put their hands or eyes on them when they need them. ...

Photo by Alexas Fotos from Pexels. There are many flavors of technical writing. Mine is software. One of the constants of any software team is the change that comes with employee churn. People find new opportunities by joining your team. People find new opportunities and leave your team for elsewhere. ...

Photo by Moose Photos from Pexels. I would like to thank the tech writers in the Write the Docs Slack’s #lone-writer channel for bringing these ideas to the top of my mind. Everyone suffers from a bias of familiarity when looking at our docs. Once you read something once, the next time you read it the mind can anticipate and insert what it remembers and expects to be there. This happens whether the expected word or phrase or punctuation is there or not. ...

Photo by Suzy Hazelwood on Pexels. Are docs a good investment? One of the challenges every documentarian faces is justifying the investment in docs. Whether that investment is salary training and professional development expanded doc team tooling dev help for site development It can feel like we technical writers are always battling it out for the company’s money. And, often, the experience is that the money for conferences or books or a new team member goes to other teams instead. Teams that have a clearer line of sight from work to the bottom line of the company’s P&L statement. ...

Photo by Startup Stock Photos from Pexels. Technical writing can be an introvert’s dream. (I know, I am one!) That said, there are two communities that every tech writer needs to develop to thrive in our work. Network of co-workers and subject matter experts Other tech writers for support and professional development Why are these communities vital? And how does a tech writer go about developing them? ...