In defense of kindness in the editorial review cycle

Photo by Štefan Štefančík on Unsplash

I took an interest in editorial reviews early in my career. That interest drove me to become a technical reviewer in the computer book industry for several years. I’m not sure they even have that role anymore. At the least publishers may not pay for that review anymore. Sitting through curt and incomplete document reviews made me take those extra steps because there had to be a better way. 

Fast forward to today, I’m a stickler for kindness in the editorial review cycle:

Continue reading “In defense of kindness in the editorial review cycle”

Avoiding Mission Impossible technical writing projects

Photo by Aaron Mello on Unsplash

I’ve had the great fortune in my career to work on some very tough projects — in what I like to call documentation unfriendly environments — and won some and lost others but learned so much about technology and how to work independently as a technical writer.

Before I accepted my current position, I had the opportunity to speak to an organization which has what I quickly came to ascertain what could be a “Mission Impossible” documentation project where there would be more chances for things to go wrong than there was to go right.

After speaking to the recruiter who set up the meeting for me, I began to think how had I won the mission impossible projects versus being “the previous technical writer.” Keys to success include:

Strong technical team

A strong technical team — not to write the documents mind you — but like it or not the IT industry is peppered by a lot of smart people and a lot more people who think they are smarter than they are. If you have genuinely knowledgeable and capable people in the critical technical roles, then half your battle for extracting technical information is won in my experience. If the wrong people are in critical roles, the holes and gaps that sometimes happen in technical documentation can expose the shortcomings.

Proper technical writer/developer relationships

Relationship with the technical team where you as the technical writer isn’t an unnecessary drag on personnel or other resources. Technical writers who need their hand held or can’t work independently are only going to be set up to fail when it comes to a mission impossible project.

Product management and developer collaboration

Strong product management and technical team cooperation and communications. If Product Requirements Documents (PRDs) or stories are just being thrown over the transit without much dialog between product management and the senior members of the technical team, then the hijinks can ensue.

Access to test environments

Access to test systems and the bug tracking system because reverse engineering of technical documentation does often occur especially if the document efforts begin well into the development lifecycle.
Reality vs. vaporware can also come into play on such document projects. If for some reason, you are continually denied access to the system, don’t take it personally, but be on guard that the product may in whole or part not exist except for visions in an executive’s mind.

What are your keys to success on “mission impossible” documentation projects?


My name is Will Kelly. I’m a technical writer and content strategist living and working in the Washington, DC area. My current focus is thought leadership and technical marketing content. I got my start writing user guides, administrator documentation, online help, and later moved into SDLC documentation. My articles about enterprise mobility, BYOD, and other technology topics have been published by IBM Mobile Business Insights, Samsung Business Insights, TechBeacon, CNET TechRepublic, and others. Follow me on Twitter: @willkelly.

Building the better technical editing and QA cycle

Photo by Avi Richards on Unsplash

It’s rare when I don’t hear complaints about the technical editing and reviewing of documents and the QA cycle in general. It’s unfortunate because building a document QA process that’s supportable and replicable

Here are some considerations to keep in mind when building a technical editing and QA cycle for your documents:

Establish standards and styles

Technical editing is about standards — you need to put some document writing standards and styles in place if even informally. Writing a style guide can be a major commitment.

Set expectations for document reviews

I always recommend that organizations set expectations for technical editing and reviews. With today’s harried schedules, my recommendation is an iterative review cycle. Just give your reviewers expectations for the document at the end of each review pass.

Manage and use document templates

Microsoft Word documents can be both a boon and a drag on productivity. I recommend that you and your team both manage and use document templates for all your documentation. Managing templates includes documenting the styles writers should use; being responsive to any template issues, and promoting proper template usage.

Use document versioning and workflow

Use Microsoft SharePoint or some other online collaboration platform for document versioning and workflow adds security and transparency over the process that sending email back and forth cannot touch. You can always roll back documents to a previous version.

Have the editors use the technology

Anybody you task to edit your technical documentation needs to use the technology. Nothing can go further to discredit the technical editing of a document than changing the meaning of technical content and the out and out introduction of technical inaccuracies. While this may not always be feasible, being hands-on with technology is one thing I strongly recommend for all technical publications people because it helps them be more self-sufficient among other things.

Instill the importance of technical accuracy

Somewhere along the line, the myth that technical writers and editors don’t need to be technical somehow began to perpetuate itself. This tale is just not practical and wrong on so many levels especially in today’s down economy where all project team members have to carry their weight and then some.

Attention to technical accuracy throughout all phases of the technical editing and quality assurance process means no last-minute rush of having to edit where the editor has changed the technical meaning.

Develop a constructive dialog between editors and writers

Technical communications is a team effort whether it is publishing a user guide, technical article, and about any technical content. Neither the writer or editor is the last bastion of quality (or at least they shouldn’t be), so it is prudent to foster a constructive dialog during a technical editing and QA cycle.

Questions back and forth between the editor and the writer are a good thing. You want them to resolve issues upfront that leads to changes in technical accuracy in the document.

Manage and take ownership of the process. Locking a technical document up in an endless review cycle doesn’t do the document or the team any good. Build a transparent process that is easy for all participants to follow does wonders for putting out a quality document.


My name is Will Kelly. I’m a technical writer and content strategist living and working in the Washington, DC area. My current focus is thought leadership and technical marketing content. I got my start writing user guides, administrator documentation, online help, and later moved into SDLC documentation. My articles about enterprise mobility, BYOD, and other technology topics have been published by IBM Mobile Business Insights, Samsung Business Insights, TechBeacon, CNET TechRepublic, and others. Follow me on Twitter: @willkelly.

5 reasons why your enterprise social network won’t improve your document reviews

Photo by Lauren Mancke on Unsplash

Through my work as a technical writer, I’ve become a student of document reviews especially those performed by geographically dispersed work teams. You may know from your own experience that document reviews can be a painful process — often times poorly enforced, planned, and scheduled — meaning that some may want to throw new tools at the problem looking for some sort of cure all over this age old issue.

The rise of group chat tools such as Microsoft Teams and full-blown enterprise social network (ESN) platorms

  1. Document reviews typically fall to the end of the project cycle. Like it or not, you’ve probably seen your document reviews happen in the closing days of the project where reviewers are often times going in multiple directions. Outside of another communications vehicle, social media can’t help much here.
  2. No built-in enforcement/accountability. Document reviews require levels of enforcement for management and accountability for reviewers this is doubly true for geographically dispersed project teams.
  3. ESN lacks definable standards and processes. You can shore up a new or existing process with ESN tools but a document review requires definable standards and processes.
  4. It’s just another tool to learn for some users. I am a big proponent of today’s web-based collaboration and project management tools but am the first to admit that not everybody shares my interests and passions
  5. Collaboration & ESN aren’t always baked in. While social media and online collaboration have great promise within the corporate enterprise there is always going to be the organizations, teams, and users who aren’t going to be comfortable with the communications and transparency that the tools provide in a document review.

Are the technical writers in your organization using ESN tools for internal communications?


My name is Will Kelly. I’m a technical writer and content strategist living and working in the Washington, DC area. My current focus is thought leadership and technical marketing content. I got my start writing user guides, administrator documentation, online help, and later moved into SDLC documentation. My articles about enterprise mobility, BYOD, and other technology topics have been published by IBM Mobile Business Insights, Samsung Business Insights, TechBeacon, CNET TechRepublic, and others. Follow me on Twitter: @willkelly.

Using Trello for managing editorial projects


My work as a technical writer sometimes means having to manage my own projects yet communicate about them in a way that programmers and engineers can understand without having flashbacks to college freshman English. I’ve come to use Trello for managing document projects. Technical people are comfortable with the tool and I can speak to project status in terms they can understand.

Here’s how I use Trello to manage writing projects:

  • Set up a Trello board split into all of the phases (using columns) of content development including conceptualization, writing, editing, review, layout, and final publishing. I also include a project backlog columns to help me track project ideas that come out of meetings or I want to capture in anticipation of future requirements.
  • Create a card template (conveniently stashed in the Backlog column) that I use the checklists feature to map out an editing checklist I groom govern editorial quality and style. I also use the checklist to help remedy any of my usual writing mistakes.
  • Revise the project cards over time to keep my editorial checklist sharp such as when I make a stylistic decision that I don’t want to forget.
  • Use labels so I can slice and dice views over the documents I have in progress. For example, I use tags to specify audience, document type, and corporate group.
  • Display Trello on meeting room projection screens when I want to talk about writing projects that are currently in progress
  • Use the Trello iOS app on my iPhone 8 or iPad Pro when I’m at home and want to review progress on a document.

Trello helps me stay on course especially when I’m working on smaller documents in a work environment with ever shifting priorities. I use it to create a visual picture of my progress especially when I get blocked on a document because of team availability.

You don’t have to be faithful to agile project management or Kanban either when using Trello to manage projects

Another benefit of Trello is that I’ve found it easy enough for even non-technical users to understand. For example, let’s say you need to share a Trello board with your marketing department. They’ll have a minimal learning curve if at all. One of my concerns when Atlassian acquired Trello that it would be subsumed into the Jira mothership, I’m glad to see that Atlassian realizes that there’s room for an entry level tool that won’t siphon users from Jira. I’ve tried using Jira to manage writing projects on a past contract. I found it too hard to use. Then again the client in question was trying to use Jira out of the box with no customizations or extensions.

My experience with Power Ups has been mixed mostly because I’ve been using the free version of Trello. I’m happy to see that Trello’s focus on integrations continues after the acquisitions. After all, no development team or in my case solo technical writer is an island so integration with other systems is key when managing content development projects.

Are you a technical writer that uses Trello? Share your experience in the comments.


My name is Will Kelly. I’m a technical writer and content strategist living and working in the Washington, DC area. My current focus is thought leadership and technical marketing content. I got my start writing user guides, administrator documentation, online help, and later moved into SDLC documentation. My articles about enterprise mobility, BYOD, and other technology topics have been published by IBM Mobile Business Insights, Samsung Business Insights, TechBeacon, CNET TechRepublic, and others. Follow me on Twitter: @willkelly.