My tips for hiring technical writers

Photo by Charles Deluvio 🇵🇭🇨🇦 on Unsplash

I’ve written about hiring technical writers two or three times in the past with some impressive results. In fact, my initial article garnered me some not very nice emails from technical writers. It’s a timeless topic, so I wanted to go back and see if any of my initial advice and thoughts have changed in light of today’s economy.

There are still a lot of contrasting viewpoints on the role and skills of the technical writer that can even be confusing to technical writers themselves. This unnecessary confusion also leads to the fallout that affects the salary and career mobility of technical writers. But as a hiring manager, it gives you more room to craft a technical writer position that can be of full benefit to your organization.

Here are my tips for hiring a technical writer:

Throw out preconceived notions about the role

Writing your own job description for the role may seem like, but it means digging down and looking at where your technical documentation needs to go, the challenges getting there, and then when you get there how to maintain the documentation and ready it for the next step. If you’ve had bad experiences

Ask for what you want in a technical writer

It’s one thing to write the technical writer job description that fits your organization’s needs and doesn’t create more drag coefficient on your development team and the project as a whole. Yet, even in today’s down economy be prepared to pay the freight to get a high-end technical writer. This might mean securing more budget and also cutting out third-party recruiters with their 40–65% markup on contractor’s hourly wages.

Align the technical writer to your business

Academia and graduate degrees have really polluted the waters of technical writing and other professions like instructional design. Theory is no substitute for real experience delivering technical content.

Also, graduate degrees are no substitute for real-life experience. Look for technical writers that have worked in your industry or a similar one.

Contractor? Contract to Hire? FTE?

My recent look at my local market shows that the majority of technical writer positions are now 3– 6-month contracts. Full-time employment positions are in the minority.

If you have budgets and project timelines to contend with then starting out with a contract technical writer might be the way to go for your organization.

Look for an experienced technical writer who looks like they have a history of coming into new projects, learning the product, and documenting it in your industry or a similar one.

Contract to hire is the way to go depending on your budget and is an opportunity to have a shakedown cruise with a technical writer especially if you’ve been burned by technical writers in the past and/or rethinking the future of technical writers in your organization.

Look for evidence of technical curiosity

A good technical writer needs to be curious about technology. It’s not they need to be a programmer or engineer, but it’s the technical curiosity that drives them staying up to date with technology. There is an industry myth about “ignorance is an asset” that some lazy technical writers still try to push on people especially hiring managers new to bringing on technical writers.

It’s not about “ignorance,” it’s curiosity that drives a technical writer to learn new technologies and figure stuff out. Technological ignorance in a technical writer will only cost you an annoyed development team and lengthier document review and editing cycles on the project backend.

Rolling your own technical writer job description and ignoring the confused nature of the technical writer role today is the best way to get your documentation written without an unnecessary drag on your other team members.

How do you hire technical writers?


Hey there! My name is Will Kelly. I’m a technical writer and content development manager living and working in the Washington, DC area. After spending years focusing on technical and SDLC documentation, much of my work now focuses on thought leadership content and marketing collateral. My articles have been published by DevOps Agenda, Mobile Business Insights, TechBeacon, CNET TechRepublic, and others. Follow me on Twitter: @willkelly.

Conducting a tech documentation audit: The first 30 days onsite as a technical writer

Photo by Mimi Thian on Unsplash

A typical interview question I’ve gotten in the past is what do I do when I come in as a new technical writer that is the first one inside of an organization. Some of my technical writer roles in the past have been working directly on technical teams (and have been the first technical writer more than once), so I do have a process I’ve come up with over the years but had yet to write down. The key for a successful document audit is to couch everything in business terms especially if the technical writer position is to either start a new group or be a part of a technical team.

Here is a basic overview of my documentation audit process:

Get access to existing documentation

I like to read all of the existing technical documentation before speaking to anybody. At this phase, I want to look at the documentation based on my own experience tempered against any preliminary discussions about the current state of the organization’s technical documentation as discussed during the interview stage and any preliminary talks that have taken place. I usually keep a running list of observations of what I see in the documents at this stage.

Get access to existing systems (if feasible)

An optional step is to get access to existing systems to compare the existing documentation against orders for a document freshness test. However, I realize this isn’t always feasible or even necessary, but I’ve gotten a lot of insight doing this when the project involves reverse engineering requirements documents, software requirements specification, or functional specifications.

Discuss organizational priorities for technical documentation

I don’t admit to having all the answers about the direction of the documentation plan, so I always try to get the organization’s priorities for technical documentation early in my documentation audit. Technical documentation needs to align itself with the business early in the process.
Interview internal customers about the documentation

I’ve long been a believer of aligning technical documentation to the business, so I am a big proponent of talking to the internal customers for the documentation and getting a handle on their likes, dislikes, and requirements.

Interview stakeholders and managers about the documentation

After speaking with the internal customers about the documentation then it is time to talk with the manager and higher level stakeholders of the documentation.

Develop and present a list of findings

Based on my discussions with staff members, I write up my list of outcomes and introduce them to management and/or stakeholders either through a written report or a presentation.

Develop an action plan

Based on the discussions during the internal customers and stakeholders and the presentation of the list of finding then it is action plan time. My action plans typically include:

  • Document priorities
  • Proposed document overviews
  • Create Project schedule/dates for document development
  • Execute on the action plan

I like to align my action plan with the projects that the documentation supports and set 60 and 90-day goals for new technical documentation efforts especially if technical writing is a new addition to the organization.

What sort of upfront analysis do you do as a technical writer starting on a new contractor in a new full-time position?


Hey there! My name is Will Kelly. I’m a technical writer and content development manager living and working in the Washington, DC area. After spending years focusing on technical and SDLC documentation, much of my work now focuses on thought leadership content and marketing collateral. My articles have been published by DevOps Agenda, Mobile Business Insights, TechBeacon, CNET TechRepublic, and others. Follow me on Twitter: @willkelly.

My thoughts about documenting SaaS versus traditional software

Photo by Andrew Neel on Unsplash

My experience writing documentation for cloud and software-as-a-service (SaaS) solutions has evolved over time. I spent a good bit of my career documenting large-scale systems and data center operations so I guess you can say that I appreciate playing at scale. The timelines for documentation were generous, review cycles came during the end of the publishing lifecycle, and document delivery took the form of a Word document or Adobe Acrobat PDF file.

Documenting traditional software

I used to follow a framework similar to the following when documenting traditional software:

  1. Get access to the application I’m documenting and get my hands on any source material available such as requirements documents, software requirements specifications, and design documents
  2. Take some time to work through the application myself without assistance from the developers, product manager, or operations
  3. Align my documentation schedule with the overall development schedule
  4. Write a first draft of the documentation based on what I can create from self-exploration and research
  5. Submit draft for review by SMEs
  6. Complete review comments
  7. Publish document

Granted I often would customize my documentation processes to meet appropriate organizational staffing and cultural requirements. For example, there have been times in the past I had to put more buffers into my processes because invariably documentation fell down the list of developer priorities but I still had to press on to complete what I could finish on my own,

I’ve written documentation for cloud and SaaS-based customer service, cybersecurity, and backend telecommunications applications. During those projects, I wrote user guides, implementation guides, operations guides, administrator guides, and related content. I spent time believing that developing WebHelp with MadCap Flare was the ideal solution and format for those documents. However, the rise of agile and DevOps made me reconsider because my publishing philosophy began to evolve from technical writer-centric to more team-centric. For example, let’s say a developer needs to swap out some code samples.

In fact, writing technology articles for publication would influence how I document SaaS and cloud applications in the future. I remember when I was freelancing for CNET TechRepublic, I learned how many people turn to Google for help even before vendor documentation. Technical articles fill a significant knowledge gap for some consumer and more technical users alike.

Documenting SaaS or cloud applications

My framework for documenting a SaaS or cloud application right now would follow the same general flow I’ve had success with in the past.

  1. Get access to the application I’m documenting and get my hands on any source material available such as requirements documents, software requirements specifications, and design documents
  2. Take some time to work through the application myself without assistance from the developers, product manager, or customer success
  3. Create a topic-based outline and use a project management tool such as Jira, Trello, or Asana to manage topic development down to editorial checklists and other steps to guide the topic from draft until final
  4. Set priorities for the topics to document and develop a publishing and review schedule
  5. Work the publishing and review schedule as planned
  6. Publish the document and topics on a regular cadence based on updates and revisions.

Mind you such a framework I propose needs to be replicable and supportable by the writing, editing, and subject matter expert (SME) reviewers on the project. I also make it a practice to document the content creation process I’m proposing for a contract or a new job.

Thinking ahead

If I were to document a SaaS platform today, I would look for ways to publish the documentation to Atlassian Confluence or a cloud-based service desk solution. WebHelp and other help formats just don’t lend themselves to iteration in my experience.


Hi! My name is Will Kelly. I’m a technical writer and analyst based in the Washington, DC area. I’ve worked with clients such as NetApp, Dell, and Neustar to develop technical, training, and thought leadership content. My articles have been published by IBM Mobile Business Insights, TechBeacon, CNET TechRepublic, Toolbox.com, ZDNet.com, and others. Follow me on Twitter:@willkelly.

Does a technical writer make for the worst patient?

Photo by Martin Brosy on Unsplash

I was quick to put my technical writing experience and skills to work after I got my Thyroid removed. My goal was to become my #1 patient advocate. My first big culture shock was the differences in how the IT and medical community about how they troubleshoot issues.

Having been on my fair share of failing IT projects, I look for patterns when something wrong occurs. I call this the last plugged in/first unplugged method. The medical profession doesn’t prescribe to this method of troubleshooting. My current Endocrinologist and I communicate well. He understands (and maybe even appreciates) my technical writing background. Prior Endocrinologists were either dismissive of me and my post Thyroidectomy problems or told me not to worry so much.

I remember when I used to attend THYCA meetings. Another attendee brought up the fact that endocrinologists are chemists at heart and that influences how they diagnose patient issues. Until my current endocrinologist, I found that my communications and troubleshooting methods from the IT world didn’t mesh with Endocrinologists.

My information gathering and research skills also have come into play. I made extensive use of Evernote to capture and track information related to thyroid issues and my medical treatment. There were times I wish I did better in science when I was in school, but I am still learning until this day. Staying on top of all this information whether it is my research, insurance company correspondence, billing, and test results became a project unto itself. While I am in a good place with my current Endocrinologist, I still work to refine my research and stay informed. My technical writing experience gave me the tools to compensate for lack of a science degree.

Throughout it all, I came to understand, how some patients might get lost in the Thyroid industrial establishment and never get better. I saw how doctors can be skeptical of the symptoms thyroid patients describe.

Navigating the medical establishment to get the best treatment has been a challenge until my current Doctor. I wouldn’t have gotten to where I am at if I didn’t put the communications, research, and online skills I learned as a technical writer.

Did I mention that I never liked seeing Doctors or getting needles? Both things are old hat now. I continue to adjust my strategy based on everything I learn from my research ever hoping to have a better connection with the medical establishment.


Hey there! My name is Will Kelly. I’m a technical writer and content development manager living and working in the Washington, DC area. After spending years focusing on technical and SDLC documentation, much of my work now focuses on thought leadership content and marketing collateral. My articles have been published by DevOps Agenda, Mobile Business Insights, TechBeacon, CNET TechRepublic, and others. Follow me on Twitter: @willkelly.

It’s coming up to the end of the year

Photo by tribesh kayastha on Unsplash

Thanksgiving snuck up on me this year. It caught me by surprise. So much so, I’ve been tallying up all the things I hope to get done by December 31, 2018.

Here’s a few of the items I have on my to-do list for the end of the year:

  • Finish up some big projects at work dealing with Cloud Computing
  • Complete some personal writing projects that’ll show up on this blog, Medium, and on my LinkedIn profile
  • Launch a new version of willkelly.com running on Drupal
  • Prepare to move this blog to self-hosted WordPress when my WordPress.com account comes up for renewal
  • Take the week off between Christmas and New Years for a little staycation action including a day where I just read books the whole day long

What personal projects do you have to finish before the end of the year?