Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

During my 5 years in IT as a software developer, I've noticed that developers have a strong distaste towards doing any documentation. The act of taking screenshots and creating documentation seems to be a painful and time consuming experience. In one company I worked for, we had a technical documentation team with two technical authors and they developed all the user guides for our customers. In other companies where I've suggested hiring a technical author, I've been told they are not worth the money, but I'm a little unsure if that rings true. Is it better to have developers stop coding and take half a day to do screenshots and create the various guides or is it worth hiring someone who handles such tasks?

share|improve this question
    
You must be thinking of very small applications. "Half a day" for screenshots and guides is wildly optimistic. Some projects have documentation needs can be counted in man-years and this is not counting the training sessions that need to be developed for end-users. There's a lot more to it than screenshots! –  Angelo Dec 19 '11 at 14:10
1  
@Angelo, agreed. There is certainly a lot more to it, which is why I'm curious why a lot of the IT companies I've dealt with don't have technical authors in their team. It's a time consuming activity for a large project, as you mentioned. –  Desolate Planet Dec 20 '11 at 17:15

4 Answers 4

up vote 4 down vote accepted

I would say it ultimately boils down to how skilled the developer is at writing technical documentation and how much pressure they are under to do other development related work instead, as this will obviously affect the quality.

If you have developer(s) who have the time and skill to write quality technical documentation, then great, because no one knows the software better than the developer.

Advantages of using an 'outsider' for the technical documentation is that they can write from the users perspective and note things that the developer may not, as it may have already become so ingrained to their routine.

The documentation can also be a reflection of the quality of the software, as it may be the first place the user goes before installing/buying, especially if your audience is already technical so it's important to get this first impression right.

So, in summary, yes they are valuable to any team and the expense they incur is ultimately worth it (they don't have to be a permanent fixture and you free up some development time too).

share|improve this answer

The technical writers on my team largely act as editors.

We understand our system better than they, and they understand the written word better than us.

As developers, we are responsible for documenting our own work, and the technical writers work to normalize the widely varying style and quality our team produces.

share|improve this answer

I've been a technical writer for over 20 years. Most developers dislike writing documentation. If you do not like doing something, you aren't likely to do it well. Do everyone a favor and hire a professional. You wouldn't expect them to write the marketing or sales materials would you?

share|improve this answer

A good technical writer is an asset to any development team. Our last technical writer was a superstar:

The last technical writer we hired started by interviewing each developer, and building a help document, combined with tutorials, for our software. She then started scheduling regular meetings for updates, as well as interviewing each developer once they completed major projects, collecting information for updating the documentation.

Once our documentation and tutorials were up to snuff, she installed a sharepoint server for storing all of our documents and written knowledge, which she consistently edited and kept up to date - including monitoring documents that had not been edited for weeks or months, and asking the authors for any updates. She installed a wiki and knowledge base for our support team, which she seeded from the (by then) copious amounts of information she'd collected from developers.

She got together with our trainer, and helped him write up a training document for any new hires and potential clients. She then made sure that the document was kept up to date, and edited it to keep it legible and clean.

Throughout, she consistently edited and cleaned up all written information, whether it was wiki, sharepoint, product documents, etc... that went her way. If she ever had spare time, she volunteered to help us write any presentations we had to make to other teams and to each other.

She managed to become a product expert along the way, and moved on to be a highly paid consultant for one of our clients. We were sad to see her go.

share|improve this answer

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

Not the answer you're looking for? Browse other questions tagged or ask your own question.