Maintaining technical documents: A primer

While maintaining technical documents can be the most boring part of the technical writer’s job in some organizations, it’s a necessary part of the business especially in policies and procedure driven environments.

However, updating documents often falls down the list of priorities and becomes a reactionary task versus a natural element of business operations. Becoming a reactionary task leads to such a simple task being flubbed and lapping up more resources and operational budget than first thought.

I see more smaller contracts now for writers to come in and update technical documents especially policies and procedures guides and got to think how I like to update documents:

Preliminary setup

Use track changes. Even if you are only using a single technical reviewer for your document(s), it is best to use Microsoft Word’s track changes for inputting edits and comments. It’s works even better if you make sure everybody involved in document reviewing has their name and initials filled in under Tools>Options on the User Information tab. Using track changes enables everybody involved in the document review to see who made which edits and comments. Track changes makes it easy when you need to track down a commenter for clarification on a comment.

Use SharePoint or another collaboration platform. Email and the Outlook Inbox are, unfortunately, traditional document management tools in some organizations that double as the workflow for document reviews. While sending documents back and forth is often times “baked in” to teams, putting documents into a SharePoint document library or on another document management or collaboration platform helps to lock down document versioning and ensure that everybody involved in the document cycle is using the same document.

Consider a document version history in the document front matter. If you are reviewing technical documentation, you may want to consider a document revision history page in the front matter of your documents if you don’t already have it in place.


Conduct a document audit and initial edit. It’s easy to sit around a meeting table and poke holes in a document that you are seeing for the first time. What I like to do first is get a feel from the document owners what they see as the strengths and weaknesses of the documents. Then I ask questions like, “What is the freshness [age] of the document?” and “What issues in the document standout?” After seeing where my line of questioning takes me, I then like to do a first pass edit to take care of the big stuff.

Question and comment. Years of working as computer book technical reviewer taught me how to write clear and substantive comments. It’s important to drill into technical reviewers (especially the new ones) that their comments need to be constructive and if a technical fact is wrong that they should provide the information to make the correction.

Open a dialog with the author(s) and/or document owners. It’s easy to treat document technical reviews as solo efforts when, in fact, an open dialog can work wonders at review time. Encourage an open dialog between the author and reviewers and

Post Review

Use a central repository for documents. Get the documents off people hard drives and out of their secret stashes so they are secure but accessible to project team members, stakeholders, and customers.

What I’ve outlined in this post is a basic framework that needs to be adjusted to fit the requirements, resources, and schedule of a given organization and project.

What are your tips for updating and revising technical documents?

Image by stock.xchng user: tomdavies

Originally published at on November 27, 2011. This post has been revised prior to republishing it on Medium.

Will Kelly is a technical writer and analyst based in the Washington, DC area. His writing experience also includes writing technology articles for CNET TechRepublic and other sites. Will’s technology interests include collaboration platforms, enterprise mobility, Bring Your Own Device (BYOD), project management applications, and big data. Follow him on Twitter: @willkelly.

Take your team from inbox to collaboration

There is a dizzying array of online collaboration applications available today that can satisfy the requirements of organizations with teleworkers, virtual teams, and freelancers.

What many of these online collaboration offerings do is gloss over the best ways to move users from depending on their email inboxes and other file stashes to migrating their documents and processes online. A good implementation is platform agnostic. The tips in this post can apply to cloud-based solutions or a solution you remotely access on your employer’s network . You’ll have some work to do around user requirements, “spring cleaning” , and maintaining user productivity.

Here are some tips to better manage moving your team from their email inboxes to online collaboration:

Gather business and technical requirements. Having seen successful and failed implementations of online collaboration solutions, the lack of previously obtained business and technical requirements sticks out as one of the constants in failures. A “build it, and they will come” mentality is counter-productive to the initial move to a collaboration. The solution you select needs to account for the user community, their technical experience, and how they need to use the collaboration solution to stay productive and do their jobs.

Acknowledge organizational culture. As I’ve written about before, culture can drive online collaboration but can also sink it. Corporate culture is one of the reasons why I am a proponent of upfront planning that involves the users who are supposed to be using the application. There will most certainly be cultural shifts so plan accordingly.

Take advantage of trial periods. With all the choices out there in online collaboration applications, the bright side is many if not all offer trial periods which make for a minimal barrier of entry for piloting online collaboration applications. When running internal pilots and trials, look for a wide cross section of users so you can get honest feedback on the solutions you are piloting.

Find a champion for online collaboration. Moving from old ways to online collaboration brings with it a lot of change and perhaps baggage so I like to recommend that organizations look for a “champion” amongst the ranks. This champion also doesn’t have to be a technical person or the “collaboration geek” . I’ve come to see the best champion for online collaboration is the everyday user who has seen the benefits of online collaboration in their work or where online collaboration has resolved a business problem they have.

Perform a “team clean” of your documents. Without a central repository for project information, project documents can hide on local hard drives, shared network drives, email inboxes, USB thumb drives and a number of decentralized locations. When making the move to an online collaboration platform for managing your documents, you need to do a “team clean” of all the project related documents your people stashed away. It’s from those stashes that you need to determine what are the official documents that will migrate to your new collaboration platform.

Audit your team’s existing processes. Outside of substituting for previously email-driven processes, your online collaboration application may also have a profound impact on some of your other project and business processes depending on your online collaboration application’s features.

Implement application security judiciously (and realistically). Document security is high up on the list for implementing an online collaboration solution. However, one of the signs of a poorly implemented online collaboration solution is being too locked down often causing users assigned to work with the application takes other avenues to accomplish their tasks. Application security can be a sensitive subject in some organizations so I recommend you spend the extra time to plan the appropriate security roles for your team members so they can be productive using the online collaboration application.

Appoint a site administrator at the team level. Project teams should have the knowledge within the team and access rights to manage their own online collaboration workspaces. Centralized administration over such user tasks as creating new folders and workspaces are better left on the team level versus having to send a request to a centralized administrator or group. Rapid responses to user requests are but one of the many ways to curry favor from users who have doubts about the new online collaboration application.

Build a usable folder and organizational schema. Moving documents to a new platform should be done with care and planning. It’s always good to work as a team during the “team document clean” and later to develop a folder and organizational schema that improves upon what sufficed in the past and is usable for the team.

Have you migrated your team away from email inboxes? Share your experience in the comments.Image by Stock.xchng user: svilen001

Will Kelly is a technical writer and analyst based in the Washington, DC area. His writing experience also includes writing technology articles for CNET TechRepublic and other sites. Will’s technology interests include collaboration platforms, enterprise mobility, Bring Your Own Device (BYOD), project management applications, and big data. Follow him on Twitter: @willkelly.

Originally published at on December 6, 2013. This post has been updated and revised.

Democratizing project management data: Beyond the Gantt chart

One of the reasons why I find project management applications so interesting and have written about them in the past is because the good project management applications are communications tools at heart. Throughout my time as a contract technical writer, I’ve seen inside project management organizations of every stripe and the quality of project communications separates the good from the bad PMOs almost every time.

This experience lead me to become a big believer in the democratization of project management data.

All project management data needs to be accessible to everyone involved in the project lifecycle including executives, stakeholders, project management, and the people doing the actual work. When project managers and PMOs cage their project schedules and other management data in tools like Gantt charts, they risk losing some of the audience for the information.

I wrote about this very subject back when I was writing for WebWorkerDaily and later for Projects@Work and CNET TechRepublic, and I still find it fascinating.

The growth of cloud-based project management tools like LiquidPlanner and Viewpath are prime examples of how moving away from a strict Gantt chart view into the project lifecycle can be liberating for all those involved. Just because Gantt charts are ubiquitous doesn’t make them right.

Today’s crop of project management applications support multiple views that project teams can use to communicate project management information to their stakeholders. Not everybody can even understand a Gantt chart.

The key element of democratizing project management data is choosing an application that enables you to capture and publish project management data in a variety of formats including web, print, and even mobile device. Some qualities to look for in a project management app include:

  • Flexible views into project management schedules, reporting, and related data.
  • Central, secure, and accessible location for all project documents and artifacts.
  • Flexible data formats available for pulling the project management data into presentations and reports because there is more to life than just emailing a PDF version of a Gantt chart around the team.
  • Accessibility inside and outside the corporate firewall whether through VPN, Single Sign On (SSO) or another security measure.
  • Mobile client for access to project management data for project managers, stakeholders, and team members.

The integration of enterprise social tools with project management solutions as a whole still intrigues me at this point because of the potential for improving team communications within a project management structure.Though I am going to have to get out of the home security/federal government sector before I see anything like that in practice if at all.

Today’s harsh economic reality demands that all levels of the project team have an understanding of what is going on with the project. Such project management information also needs to stand on its own without the need for translation of any sort especially if your project teams span multiple time zones.

Image by stock.xchng user: ximes

Will Kelly is a technical writer and analyst based in the Washington, DC area. His writing experience also includes writing technology articles for CNET TechRepublic and other sites. Will’s technology interests include collaboration platforms, enterprise mobility, Bring Your Own Device (BYOD), project management applications, and big data. Follow him on Twitter: @willkelly.

Originally published at on November 5, 2011. This post has been updated and revised.

5 productivity lessons my thyroid taught me

My Thyroid — actually the subsequent Thyroidectomy I had in October 2010 — has been perhaps the most prolific productivity teacher in my life thus far. The farther I get away from the surgery the more I’ve come to realize the productivity lessons from the whole thing.

I had to bring many things to a cold hard stop and then turn things back on in my life switch by switch like bringing up a server farm or a data center. Ultimately, I am realizing the benefits and seeing how it has been a catalyst for positive change.

Here are the five productivity lessons my Thyroid taught me:

  1. Centralize your information. I had a lot of information to capture and track on all things Thyroid. Evernote played a major role here. It became my central repository for notes and important information for all my major personal and professional projects. I also now keep a folder on each of my personal and freelance projects. Taking a multi-device approach to storing certain information has made me feel on top of things more than once in the past year. I am really enjoying the Clearly plugin for Chrome to capture my online research. In fact, it is becoming a rare occasion when I use the Evernote extension except if I need to capture a web page intact for some reason.
  2. Sometimes two reminders are better than one. I have to take Thyroid medication every morning and I am not a morning person by any means. After my alarm clock sounds, I get a reminder thanks to Google Calendar to take my medication. Just in case I’m locked in a Walking Dead Zombie State, a follow up reminder from NotifyMe chimes up just in case I forget. Although I am happy to report that I have a lot more energy in the mornings now, my two levels of reminders are in place for peace of mind.
  3. Decide on what’s important. Unlike years past, I am making time for personal writing projects and even volunteer work at Church. After using some of the downtime around my surgery and getting adjusted to my Thyroid medication, I took the time to really figure out what I want in My Second Act (What I am calling life after my Thyroid surgery). Now I am working on putting some plans into action
  4. Watch your scheduling and natural rhythms. The late Doug Demars, my college creative writing professor, taught me that there are morning writers and there are night writers. I most definitely fall into the night category. While writing at night isn’t feasible for many projects (and my social life), I factor in some night writing time into my weekly schedule. At a broad level, I live by my Google Calendar and its email and SMS reminders.
  5. Eat smaller meals through the day versus three larger meals. Thyroid issues made me rethink the way I eat during the day. Therefore, I consulted two colleagues and friends who are into long distance running, started going to a nutritionist, and have overhauled the way I eat. It’s helped immensely with my energy that in turn fuels my productivity.

Have you ever learned any productivity lessons from a health issue?

Image credit: by Dream Designs via

Originally published at on March 24, 2012.

Will Kelly is a technical writer and analyst based in the Washington, DC area. His writing experience also includes writing technology articles for CNET TechRepublic and other sites. Will’s technology interests include collaboration platforms, enterprise mobility, Bring Your Own Device (BYOD), project management applications, and big data. Follow him on Twitter: @willkelly.

5 reasons why your document reviews aren’t working

I’ve long been a student of technical document reviews. So much so, I worked as technical reviewer for some computer book publishers to learn more about this critical element of the technical communications development standards (and that I thought I could do a better job than the reviewers where I was working at the time). Editorial and technical reviews are integral parts of the technical publications process, but oh so many organizations fumble through the review cycle unnecessarily.

  1. No Process. I stopped being surprised years ago about how often that organization’s don’t know how to review their technical documents effectively even when they have a technical writing group.
  2. Reviewer Likes vs. Standards. We all have our own likes and standards when it comes to writing. All document reviewers need clear and well-documented guidelines for the review cycle to keep them on task so the document they are reviewing meets organizational/client expectations.
  3. No Ownership. Just like other parts of the process, somebody needs to own the document review cycle whether it is a project manager or a technical writer and track the progress of the review cycle. The owner of the review cycle
  4. No Accountability. There needs to be a level of accountability for both the writer(s) and reviewer(s) to shoot for the highest level of technical accuracy they can achieve within the constraints of the documentation projects. Development teams and technical writers can build in tools for achieving better technical accuracy through such means as technical writer access to test environments, fostering a culture where it is OK and acceptable to ask constructive questions.
  5. The “Idiot as a User Advocate” standing in for the writer, editor, or reviewer. Knowing your audience and the technology being documented is critical to a document review. While there are still those hold out technical writer is only going to cause havoc on a writing project unless they can separate what they don’t know about the topic versus what the audience doesn’t know and needs to know. Editors without a grasp of the technology can also hamper the document process by introducing in technical accuracies instead of making appropriate queries and questions to clarify anything they don’t understand. Having such a reviewer at the end of the document development process can also be counter productive to the review as the reviewer can only focus on what they themselves don’t understand versus the intended audience of the document who may indeed be more technically savvy and astute than the reviewer.

Image by user: deboer

Will Kelly is a technical writer and analyst based in the Washington, DC area. His writing experience also includes writing technology articles for CNET TechRepublic and other sites. Will’s technology interests include collaboration platforms, enterprise mobility, Bring Your Own Device (BYOD), project management applications, and big data. Follow him on Twitter: @willkelly.

Originally published at on September 8, 2010.