Non-technical and Technical Writing
One particularly challenging assignment we experienced was working elbow-to-elbow with an engineer. Upon release, the company had found their high-end systems monitoring and analysis tool was causing customer’s mainframe systems to crash. For a hectic five weeks, we worked alongside the developer, testing his fixes and documenting the software in pace with his changes. Some time later, walking down a hallway, he said, “You’re really a technical technical writer, aren’t you?”
A technical technical writer doesn’t just accept on faith what he doesn’t understand. He reads the specs, if existent. He gets into the internals of how something works. He installs the software himself. He runs the application, working to achieve an understanding of how it works. He presses to gain a knowledge of the product from both the developersand the users’ point of view. He asks questions and challenges those things which may not make sense. He wants to know why and how.
And for all his strength in the technical arena, he strives to remain a “naive” new user, working with the product as if it were new to him. For example, entering unexpected commands, leaving processes half-unfinished and starting something else, and so forth. He watches to see if the system handles these unexpected actions elegantly, or does it break and return unanticipated and confusing results.
In this way the technical technical writer is able to absorb the most difficult-to-comprehend, complex, obtuse body of information. He culls through all of the information he’s gathered for what’s most important — to the end user. This includes the kind of details you find only by talking to the architects, designers, engineers, and developers. You probably won’t find it in the specs.
We have experience developing user guides, getting started guides, policies and procedures, API References, technical data sheets, and much more.
In the real world, given a printed copy of a well-written manual, the user should be able to plunk the book off the shelf, whiff through it ’till he finds what he wants—hopefully before he forgets what he is looking for—and then plunk it back on the shelf. If only. (In the online world, the action should be equally swift. You might call this action click click back back .)
Given sufficient lead time, the writer digests, condenses, and translates the information into plain English for the rest of us. Sometimes, pressed for results, he relys on intuition, gut, and a prayer. He organizes the information into a navigable whole, a body of information that is accessible to the uninitiated. So that to the end user it doesn’t appear so technical after all. This is after all, our primary goal.