Working with Developers

Many technical writers work in organizations where in their contributions are not understood. Their work is seen more as a luxury than a value-added to business. This develops a lack of respect which is shown in many ways:

  • Disinterest in sharing information for creating the documentation.
  • Disinterest in reviewing the documentation. But, do not to equate lack of time to lack of interest. They are two different issues altogether. Not getting to know, or see, or use the changes to the product until late in the development cycle. There should be a reasonably sufficient time between the code freeze and the final draft of documentation.
  • Writers are pressurized to produce quality document without enough staff.

This scenario can be changed by educating the engineers/developers, improving the quality of documentation, reducing the support calls, and by improving the overall documentation process and practices.

Understand Them

It is very important to think from the point of view of the developers. You should understand that the engineers/developer/programmer also work under tight release schedules and unrealistic demands. The SMEs expect you to:

    •  Be curious about the product you are working on.
    • Educate yourself about the technology/functionality you are going to work on before approaching them for information.
    • Understand and appreciate their tight schedules and give them time and space. You on your part should understand what is expected of you and try to create a working atmosphere that is mutually beneficial. This will improve the present thought process, relation, and situation.

Try out the products and understand the concepts before approaching the SMEs.

    • Schedule meetings (with the agenda) with them and make full use of such meetings.
    • Do not send an SOS email or make an urgent call for a minor problem. First try to solve it yourself, check if there are alternate methods and write about your concerns to them.
    • Give them a gentle reminder that you are going to send the document to them for review, so that they can expect it and plan their schedules accordingly.

Develop a Process

Include the technical review as the part of documentation process and formalize procedures for conducting technical reviews. Try to include documentation as an integral part of the product development life cycle. Having done all these, you should not forget to schedule adequate and enough time for reviews. Include reviews in the documentation plan and mutually agree to the dates by which you expect to receive the technical review feedback/comments. Try to work in close co-ordination with the development team.

    • Attend the development meetings. Not all the information discussed in the meeting will be of direct help to you, but they will be helpful in identifying the progress of work. It will help in setting and scheduling the task dates.
    • Write functional specifications for the development team. Though it may not fall under your scope of work, you will gain valuable information by doing this task.
    • Review the user interface (UI) for usability and consistency.
    • Maintain a database of tips and error messages which can be used to be a part of the trouble shooting document.
    • Edit the comments in the source code.

Improving the writer-developer relationship not only helps in improving the quality of documentation, but also creates a pleasant and friendly working atmosphere.

Advertisements

5 Responses

  1. I really like reading this article. Keep up the good work! You understand, many people are hunting round for this information, you could help them greatly.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: