Technical Writing Strategies

User Involvement

The perils inherent in ignoring users while developing a product are as obvious as they are prevalent. Only a very few software projects consciously involve end users throughout the whole process. So almost every project is plagued with misunderstandings, slow communications, unclear requirements, and unrealistic expectations.

Yet, most often the developers get together in a room with a white board and cobble together bits of structure, hoping to support functions, that may or may not be of value to the users.

So what can we do about it?

If we look at the Systems Development Lifecycle, we can see that User Goals ought to be our focus:

The key processes always have to start with the User. How could it be otherwise?

Show more

Technical Writing/Cost and schedule estimating

All projects cost time and money.

It is important to accurately estimate how much a project will cost.

Most projects are late and more expensive than planned.

Cost and Schedule Estimates for Documentation

According to a study on Estimating Software Costs, documentation accounts for 10% of the total cost of a project.

Show more

Technical Writing i18n l10n and g11n

Localization, Globalization, and Internationalization

With the same products being used around the globe, it is important to adapt products to local markets particularly where the original comes from a different culture and language. Not only does the product require adaptation, but the technical guides and Help system associated with those products require adaptation. The adaptation of a product includes shortening UI descriptions, creating UI's with a global appearance, and so on.

The abbreviations for globalization, localization, and internationalization are based on taking the first and last letters of the word, using the lower case form, and the number of letters in between: g11n, l10n,and i18n respectively.

Show more

Technical Writing UI Design

Color

Choosing the right colors to use is a very important aspect of user interface design. Choosing a color palette that makes it easier for the user to distinguish content is essential.

Avoid using disturbing colors and try to keep the general appearance pleasing to the eye. Certain colors are extremely difficult for color blind users to read, e.g. shades of green and red.

Designers of user interfaces should try to limit the number of colors to three or four. Contrasting colors should be chosen carefully and there should be a distinct difference between the color of the text and the color of the associated background.

Show more