Eric Sedor is a senior software engineer at MongoLab, a cloud-based database provider located in San Francisco, and frequent contributor to The Technical Reader. Eric cut his technical writing teeth at Shoap Technical Services before returning to his true passion, software engineering.
Very few technical writers have the luxury of being involved in a project for its entire life cycle. Most enter at the end, some in the middle, and a few arrive in the beginning. Some walk into a situation for only long enough to compose a single document. Others are responsible for quickly revising all the documents on-hand. While one might be a full-time resource, contractors are common.
Much attention in technical writing is paid to methodology and technique, but what follows is an attempt at discerning the most beneficial traits based on involvement in the project’s life cycle.
Whether a writer is involved in a traditional waterfall project (which iterates once), or a new-fangled agile project (in which two or more cycles are being developed concurrently and repeatedly), a writer can inform his or her actions by paying close attention to the concerns of the moment and embodying what is necessary. In this, a writer–even a contracted one–becomes a valuable part of the team, not merely an observer who just writes things down.
Consider each of the following phases with an attention to how a writer’s involvement facilitates success when he or she has a proper awareness of the timing of his or her own arrival:
• Beginning
• Middle
• End
The Beginning
This fabled age is only whispered of in the halls of technical writing. Those writers lucky enough to participate during this time in the life of a project enjoy some of the most fluid and creative work of their careers. Sadly, few managers recognize the value of technical writing this early (but that dead horse will not be beaten here).
Typically, primary project resources are responsible for document foundations–salesmen are scribbling requirements on bar napkins, architects are laying down rough diagrams, and developers are mocking up screens and user workflows.
If technical writers are available, their work is centered on lathing these raw materials into the monoliths that will guide the project beyond its primeval origins. The project strongly benefits from writers willing to subdue their pride and offer their trust to subject matter experts (SMEs) while still developing a level of rapport that allows for interactive communication and contributes to the thought process.
Wise writers know the value of acting as sounding boards, and are more inclined to act as apprentices to the primary authors. They conduct themselves with utmost deference to the creative process that gives birth to the project and use their expertise passively in the form of formatting and organization.
The Middle
A project in full stride is a sight to behold. Laden with agreed content and prior directives, specialized resources are scattered to the winds and left to their own devices. They are deep in thought or sweating with heavy lifting. Unlike these mainline resources, the technical writer is very much devoted to collaborative activities and still requires interaction with many points of reference. But the brave are not dissuaded when they do not fit in.
When resources are brought together, they are touching base and exchanging information about progress (or lack thereof). At these conjunctions, the team is likely to dramatically modify agreements made at project inception. Managers redirect focus, shift paths in response to new conditions, alter requirements, and respond to technical hurdles.
The successful writer is foremost a listener, and devotes specific attention to accurate recapitulation of information without hurting the cooperation of the team. When updating or assembling architecture diagrams, project requirements, and resource management documents, the writer is not afraid to admit uncertainty when something doesn’t make sense, because a miscommunication in the middle stage can have great cost. As such, writers in the middle stages can be directly responsible for introducing clarity or confusion, even if they are never seen as such.
The End
At the end of projects, the tectonic forces of planning and development have drawn to a cataclysmic head. This is the furnace in which stereotypes and common horror stories are forged–the time when features are cut to compensate for delays and loose ends are tied up. If the project has been particularly arduous, the team is nearing exhaustion.
A technical writer’s responsibilities here normally involve help files, user guides, interface specifications, and any remaining compliance documents. Most users see the writer’s work before or as soon as the primary product, so it behooves the writer to focus on presentation and consistency. Yet features are in flux as they are completed, tweaked, or abandoned so the writer is tasked with ensuring his documents reflect the final state of the product. Those challenges are simply put but require delicate negotiation.
Because in these latter days, as project resources are devoted to completing their own lingering tasks, a savvy writer engages SMEs decisively, works intelligently and independently, and acts with respect for others’ time.
A danger exists that the writer’s attention to detail will harbor shadows of failure for a demoralized force, so a wise writer is mindful to avoid invectives and comes across as conscientious instead of critical.
Considerate writers accept that the documents are never perfect and understand that while resolving inconsistencies is important, their job is to deliver documents that deemphasize the impact of such. When successful, they educate users on the product in ways that do not appear incorrect, even though the observant may have logical qualms about the finished product.
The writer has an opportunity to honor the work put into the project by placing a beautiful set of documents atop the final package. The morale benefit of such a capstone (to both the team and the users) is difficult to quantify, but easy to feel.
Finally
It would be easy to extract all the traits visited in this article into a list and say that a technical writer should, like a boy scout, always be humble, patient, consistent, accurate, considerate, independent, etc. But in life as in all projects, there are always trade-offs. By emphasizing certain traits when those traits can be most helpful, a technical writer becomes an effective force multiplier for any endeavor.
The next time you are involved in a project, devote some thought to the environment, the timing of your participation, and the way your behavior given that context can help. You and the project will benefit.