Is there value in having technical authors in a software team?

Question

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?

Answer 1

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

Answer 2

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?

Answer 3

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.

Answer 4

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.