How to select an applicant with good documentation skills

Question

We are a local outsourcing company and currently hiring for a technical position (Linux/Network engineer) - however our main objective now is to find someone not only able in the Linux/Networking field but also - and mainly - keen to create documentation about everything they learn while getting up to speed with our clients and keep the documentation current.

We used to have one such guy in the past - he kept taking notes and creating wiki pages about everything important. Sadly he left us some time ago and the team's docs quality has gone downhill very quickly. Our engineers can certainly be pushed into writing some docs but they only do enough to get the managers off their backs, but not nearly as a useful resource. I accept it - some people are born writers some are not (and I'm one of the latter group, I admit).

What interview questions would you use to identify whether someone is that kind of documentation freak that we now need?

Answer 1

To all the pompous people who think that documentation is somehow not a useful thing or below their dignity, please try working with code/systems that are undocumented and/or not self documenting. Sure, you can use your brilliant engineering mind to figure it all out. But, you'll lose a lot of time. You might even make mistakes and then start over. So, please spare us the "developers should not make documentation" slogans.

EDIT - Refer end of answer.

I am not a professional & have never hired anyone. But, here are a few suggestions for how you could judge a person's interest in documentation.

1 - Ask how they feel about writing documentation.

Personal example - I absolutely love it. Actually, I love teaching and simplifying things for others. Maybe that is where my love for documentation comes from. I like to keep it short, but informative.

2 - Ask the candidate about their frustrations with badly documented systems.

Personal example - It took me 2 months to understand something that could have been understood in 1-2 weeks.

3 - Ask about how they improved documentation at their previous company, or how the documentation they wrote has helped people.

Personal example - People often used to ask me how to use some features of internal apps. I saw too many requests of the same kind. So I created detailed documentation for it. Next time, I just shared the links to the docs. I never got any further requests after most of those requests. Maybe I did a good job.

4 - Ask them to describe an everyday object, and listen closely.

Notes - Consider that an audience does not know what a car is. I know people who'd begin describing a car in terms of engines, combustion, thermodynamics etc. when they should really be talking about 4 wheels, steering and moving from place A to B.

You could ask them about something that you know very well from your own work. E.g. "What is a test automation framework, and what does it really do?"

5 - Ask them to write a manual for an everyday object.

Notes - Maybe your soda vending machine in your office? See the kinds of questions they ask when describing the object. If they do not ask you the right questions, then they will not have the required information to describe it. If that happens, then their description will not be effective.

6 - Ask if they write blogs, GitHub docs, or self-documenting code.

PS - Hope this helps. I guess I just showed some of my love for documentation. Off to punching out some code!

---

EDITS

To clarify, by "documentation", I don't mean long manuals and such. It can be short too, depending on your audience. If someone wants more details (like interns), then they can talk to the developer. Documentation can have different forms. In software development, that can be self descriptive code and comments.

Answer 2

If you're looking for interview questions, there are basically two:

1. Do you have any previous job experience where you had to write a lot of documentation?
2. Are you willing to write documentation?

Other than this, you may want to get some writing examples or rely on the correspondence you get during the interview process: CV, cover letter, email.

Personally, I think your approach is only a part of an over-all solution. Documentation becomes important when it is evaluated and relied upon. Someone should be doing a periodic review of the documents. The objective should be whether or not the documents were created but are they useful to anyone else. When I create instructions for a particular task, I observe someone reading and executing the instructions and ask that they sort of "think aloud" so I can tell if I've given enough information. I take notes if there are any hesitations or questions.

Determine the purpose of the documentation and have an effective way to know if they've met that objective. Writing takes practice along with getting valuable feedback. When the consumers of the documents (or someone to simulate a future user), indicate which parts don't make sense, the writer soon learns how to communicate more effectively.

It would be sad for you to hire someone who is very good at writing documentation but over time they discover that you neglect, fail to acknowledge and give them no credit doing it. Also, they need to know that you understand the time commitment and won't pressure them to complete other tasks with unrealistic time limits and then punish them for not writing adequate documentation.

Answer 3

I myself am in a situation where I have to demonstrate that I know how to document:

1. I have answered a few questions on stackoverflow.com, and I believe that the way I answered these questions is a good reflection on how well I can write documentation.

2. I run a couple of blogs. While they need an update, I believe that they expose the quality of my technical writing pretty well.

3. If it's doable, ask to see current writing samples.

4. Back in December 1999, I successfully interviewed for a position as a marketing analyst for a high tech marketing consulting company. The core of the interview was a one-hour writing test on any technical subject. The interviewer ripped the paper out of my hand within 30 minutes - and almost gave me a paper cut - he'd seen enough, and I got my phone call the next day :)

5. If writing ability is important to you, I expect that you'd have filtered out those who sent you poorly written cover letters and resumes. A poorly written, poorly organized Linkedin profile is a no-no :)

Answer 4

Possible interview questions:

• What are the phases of the software development life cycle, and what are the appropriate documents for each of these? Key items to look for: Business Requirements, Software Requirements Specification, Software Design Specification, Test Script, and Training/Delivery instructions. Bonus points if they include a Risk Assessment as part of the SDS.
• What are the key components of these documents? The candidate's responses should align with IEEE standards for software documentation.