13

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?

8
  • 3
    If you want to know if they are a documentation freak ask them "How do you feel about writing documentation". If they like writing documentation they will tell you.
    – paparazzo
    Mar 19, 2015 at 13:13
  • 1
    The documentation role is more that of a business / systems analyst than of an engineer. Perhaps you should recruit for a combination position. Mar 19, 2015 at 16:12
  • 1
    @Wesley - If you aren't willing to do the documentation then you really shouldn't be calling yourself an engineer. Developer maybe, but certainly not engineer which implies a bit higher degree of professionalism.
    – Dunk
    Mar 19, 2015 at 20:22
  • @Dunk - Respectfully, I disagree. An engineer's role is to develop solutions, and to document their own work. It is not their role to document the work and systems of others. That is what business analysts and technical writers do. That's the reason these positions exist. Mar 19, 2015 at 20:23
  • @Wesley - As long as you agree that an engineer's role includes documenting at least their own work then I'm ok with that.
    – Dunk
    Mar 19, 2015 at 20:59

4 Answers 4

17

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.

10
  • Agree with what Jeff said - give good documenters credit for their work. Also give them incentives. You could go cheap and let them go, only to realize how valuable they were, when you have to waste time and money to figure out poorly documented things. Feb 3, 2017 at 0:57
  • spare us the "developers should not make documentation", well on ther other hand, you're often ask to write "a documentation" without a clear objective, and I won't talk about all the times I have to write a installation/exploitation documentation which belong to the system area (in which I'm not supposed to be competent since there are the system guys for that). And the thing I hate the more is when I have detail every single step (click on next, open the command by typing "cmd" in the startup menu,...) so even a five years old kid should be able to do it.
    – Walfrat
    Feb 3, 2017 at 12:32
  • I mean, do aircraft engineer write their documentation so even a five years old kid can build a plane ? Why should we then ? Just get a decent System administrator.
    – Walfrat
    Feb 3, 2017 at 12:33
  • 1
    @Walfrat - Your aircraft example does not make sense. I often see these kinds of examples given by people who don't want to document things at all or write self-documenting code. Do you or anyone here knows 5 year olds who can create a plane ? Certainly not. Then why would the aircraft engineering team create manuals for 5 year olds ? I don't know about that industry. But, I'd imagine that they'll probably create documentation on how to wire the electrical systems for electrical technicians etc. Feb 3, 2017 at 21:03
  • 3
    The bottom line is that one has to be smart about what to document and how much to document. That is something only you can figure out in your own situation. Feb 3, 2017 at 21:06
5

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.

3
  • Documentation becomes important when it is evaluated and relied upon. This is definitively the most important part, lot of us hate to do documentation and generally the argument is always the same "NOBODY AIN'T GONNA READ IT/IT WON'T BE UPDATED". Which is... still too often true ?
    – Walfrat
    Feb 3, 2017 at 12:25
  • 1
    Question 3: "Do you have any examples of your past writing you can share with us, and can you discuss how you approached those?"
    – keshlam
    Feb 5, 2017 at 5:16
  • @Walfrat - Especially when someone agrees to a tight deadline it isn't communicated that it will get done, but at a lower quality with no documentation or testing.
    – user8365
    Feb 8, 2017 at 13:24
0

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 :)

1
  • Paper? Nobody wants to see my handwriting. My writing, I hope, is another matter.
    – keshlam
    Feb 3, 2017 at 1:12
-1

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.

You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .