I’ve had the opportunity to be a guest on the Adventures in DevOps podcast twice now. Both times got me thinking about the importance of people and, in turn, the hidden role of content in DevOps. There’s far more than technical documentation in the relationship between content and DevOps.
My work as a technical writer sometimes means that I have to coach solutions architects and other technical people in the fine arts of writing. It’s a part of my work that I’ve come to find a new appreciation for over the past few years.
Here are some lessons I’ve learned:
1. Technical people hate to write, but there are reasons why
There’s a stereotype that technical people can’t write, and there’s much truth to that statement. I’ve had the fortune to work with some technical people who can write and write well. When I’ve brought up the roots of their writing hate, more than one person pointed back to some negative high school or college experience with a teacher. Another frequent response was being too busy.
2. Keep it simple for the non-writer
My rule for coaching a non-writer is to keep it simple for them. Figuring out just how to keep things simple for the non-writer happens on a case-by-case basis for me at least. Here’s a sampling of some things I’ve done in the past:
Encourage the non-writer to focus on being methodical and to break down what they are writing about on a whiteboard or on a piece of scratch paper
Encourage the logical thinking side of the technical person because of the role it plays in writing technical content
Tell them that the semicolon isn’t their friend so use Short paragraphs and sentences to improve clarity in their writing
Ask them what they need from me to be successful in writing the document and adjust my coaching approach with them
3. Encourage the non-writer to iterate on writing
I always advise anybody I coach writing to iterate upon what they write and sit on their drafts at least a day before they revise them if they have the time. It’s something I do as a writer, and I often relate my own experience with using this practice myself.
Depending on the person, I also encourage them to write a draft without editing until the draft is complete.
4. Introduce the non-writer to machine editing
Self-editing for non-writers takes time and practice for non-writers in my experience. I’m always happy to recommend machine editing tools to these people. HemingwayApp — which highlights lengthy and verbose sentences — and also Grammarly to non-writers I’m working with on a project. While these apps and others like them can’t replace a human editor, they can help serve as another set of checks for a non-writer who might not yet be confident in their writing skills.
I use that fact that AI is underlying today’s machine editing tools to make it more attractive to non-writers who’d benefit from the technology.
5. Deliver constructive and actionable reviews of what they write
It’s hard to not write in the IT industry and not have some bad experiences with document reviewers and editors. My aim is always to deliver constructive and actionable reviews of documents from non-writers that add value to their document and them.
It’s important to be seen as a collaborator, not as their freshman comp teacher. Part of this collaboration comes from being conversant in technology the document is supposed to cover. You can instantly lose credibility as a writing coach when you try to mold writing to fit your lack of understanding. You gain credibility when you write constructive comments with intelligent questions.
While I dare say that writing does bring me joy in many circumstances, the same can’t be said for technical staff. I’ve made it my mission as a coach to offer the people I’m helping a positive experience with writing.
I’m a technical writer and content development manager living and working in Northern Virginia. Over my career, I’ve written bylined articles for ITSearchOperations, DevOps Agenda, Mobile Business Insights, CNET TechRepublic, and others. My areas of interest include cloud computing, DevOps, enterprise mobility, and collaboration tools. Follow me on Twitter: @willkelly.