Sunday, July 14, 2013

Why do I need a technical writer?

Most people that have gone to highschool or university write reasonably well. But writing technical materials, such as software user manuals and documentation requires a set of skills that is not always part of their education. It takes time to master the theory and learn the "best practices" of technical writing. Hiring a skilled technical writer benefits you and your company by offering:



  • Common communication language
  • Easier presentation of the product to users and investors
  • Reduced development costs
  • Easier testing and better quality assurance

 

Common communication

Programmers and other product developers might be experts in their field but they are usually only comfortable writing for an audience of their peers. While this might be alright for presentations at conferences or seminars, a product's documentation must usually meet the needs of an entirely different audience. This is one of the reasons that many prefer blogs over text books and complex automated documentation.  New employees and users of the product need clear concise explanations to start work and to learn.

Like Solution Architects, Technical writers can translate between the developer's jargon and the simpler language the product's users require. Words aren't always the best medium to communicate a concept.  Mixing the right amount of words and graphics often communicates more effectively.

Technical writers can help you redesign a product's user interface to reduce the need for documentation. High-quality documentation reflects well on your company. When looking for capital Start-ups that have great documentation are looked at more often than those where documentation is poor. Venture capitalists looking to invest might assume that poor documentation means the product won't be much better.

 

Reduced personel costs

Good documentation reduces the need to call in experts. Technical writers think of the task from the user's perspective, not the developer's perspective. Thus, they explain better how new and old users can reach their goals. Clients and team members who learn how to complete their tasks by reading the documentation won't need support from consultants. Once good documentation is made available product developers will not be bothered with numerous questions. That saves them time and removes distractions that could lead to missing deadlines or project failure.

Both internal and online documentation should always be written in English. Doing this increases the number of potential candidates for jobs tremendously. A good example is when you need a javascript programmer but none of the potential candidates for the job can read German. English is more global and is the defacto language used in communicating ideas and instruction in software development. Having good manuals and documentation available written in English reduces the time it takes to recruit.

 

Testing products

While documenting a product or application, technical writers test the product to learn how it really works. In doing so, they often discover bugs or usability problems. Fixing those problems before you release the product ensures that your customers will never encounter the problems. In addition, technical writers often develop a more overall view of a product than is possible for its developers. who must focus intensely on their own small parts of the product.

Technical writers develop expertise in effective user-interface design, something most product developers never formally study. By proposing a streamlined, more effective interface, the technical writer frees developers to work on the more time-consuming task of making the underlying code work correctly.

 

Reduced development costs

Technical writers can write more concisely without sacrificing quality or using precious development time.  Features that were not described or that have incorrect descriptions in a use case are found more quickly. Projects management and development teams can make changes or delay working on code and features that are not used.

The most common way for companies to introduce their products to newly hired personnel is to have them sit with a veteran employee. This is not an effective method for training and learning. The veteran may be short on time or just not a good teacher.  The new employee also needs to write things down quickly and may not have understanding of what they are being told to write good notes. One of the more popular sayings in programming is "don't re-invent the wheel". Yet almost all Start-ups take the time to have new employees write the same thing over and over again.

The primary job of a technical writer is to write.  This always leads to the question of why hire someone to do something that everyone on my team can do, the team knows the products better than anyone else. Because professional writers create documentation faster than the product's developers. It is rare that a developer has acquired the skills necessary to write quickly and effectively.  You can see this in the lack of comments in their code and the need to use automated documentation tools. The most common developer myths are "my code is self-explanatory" or "the user interface makes it obvious...".  Programmers that have english as a second language maybe able to read documentation but seldom are they capable of writing it.

 Documentation in non-english languages places restrictions on who can perform the tasks at hand. English manuals allow you to utilize a greater portion of in-house personnel and makes it easier to find remote or telecommuting developers. Remote workers can reduce development costs significantly but only if they can understand what needs to be done and how things work. Hiring a technical writer also frees your core product developers to do the job you hired them to do, program.