Good documentation 'helps sales'

It teaches developers about their own products too, suggests specialist

User documentation produced to international standards and using appropriate skillsets can lend a significant boost to sales of a software product, says Phil Cohen of Sydney-based documentation specialist company HCI.

He declines to quantify the claimed improvement, but advises vendors currently relying on their own development staff for documentation to take a punt on a substantial sales increase and spend the money on professionals.

Cohen was in New Zealand earlier this month, trying to stir interest in good practice for software documentation at seminars in Auckland, Wellington and Christchurch.

The skills of a developer are very different from those necessary to explain the functioning of a product to a user, Cohen says. Good documentation writers combine an ability to write clear logical prose with a skill that often attracts less attention from recruiters — gleaning knowledge from the developers.

The process of creating user documentation entails “interviewing” the developers to find out what’s actually being built into the product, as opposed to what some high-level specification describes, he says. Although the documenters will primarily be producing material for users, their skills can be of equal use in documenting the development of the software as it goes, Cohen says.

Recruits to the discipline of documentation come from a variety of areas, from journalism to chemical engineering, largely because there is little formal training. “It’s where programming was 30 years ago, and you had a similar mix of people coming into that [discipline] then.”

Formal standards now exist in the form of IS 15910, an internationally ratified set of guidelines which began as an Australia–New Zealand standard. It’s designed to be incorporated into contracts for development, Cohen says. A second standard, IS 18019, contains “descriptive material on how to implement a large documentation process".

The professional body for the craft, the Technical Commmunicators Association of NZ (TCANZ).is holding a conference in Christchurch on September 8 and 9.

Join the newsletter!


Sign up to gain exclusive access to email subscriptions, event invitations, competitions, giveaways, and much more.

Membership is free, and your security and privacy remain protected. View our privacy policy before signing up.

Error: Please check your email address.

Tags documentation

Show Comments