On Collaboration

Openness is a faster route to better work. There are lots of ways of doing it, but I do think that as much as they pretend pure openness, successful OS projects all have hierarchy.

Mandiberg, Michael. Mandiberg.com (2009). Articles>Collaboration>Technical Writing>Open Source

Emotional States of Computer Users in Times of Frustration

If there’s one undeniable characteristic of the frustrated computer user, it’s that her patience is gone. She will not be slowly flipping through the user manual. Notice her jerky movements. If she turns to the help (which she doesn’t here), she’ll search for keywords, skim rapidly, click quickly from topic to topic. As we write for users in this state of mind, we have to remember the hurry.

Johnson, Tom H. I'd Rather Be Writing (2009). Articles>Documentation>Technical Writing>Emotions

Stage Directions Meet Functional Specifications: They Have a Lot in Common

When it comes to modern theater, stage directions—the descriptive text that appears within brackets in a script—are an important piece of the puzzle. They speak for the playwright when he is not there. They provide details about how the playwright has imagined the environment and atmosphere. They describe critical physical aspects of the characters and settings. Stage directions can also be critical in dictating the intended tempo and rhythm of the piece. Whether they establish a production’s overall tone or elucidate particular actions of characters, stage directions help tell the complete story that is in the playwright’s mind. Stage directions accomplish all of this, using a simple convention that structurally separates them from the actual story.

Lepore, Traci. UXmatters (2009). Articles>Writing>Technical Writing>Functional Specifications

Ten Commandments of Storytelling as Applied to Technical Documentation?

Anyone who reads this blog will know that I’m a strong advocate of storytelling in all forms of communications. I believe that it applies as much to technical or marketing communication as it does to your favorite novel or movie. This article applies McKee’s 10 Commandments to Technical Documentation.

Porter, Alan J. Content Pool, The (2009). Articles>Documentation>Technical Writing

White Papers: How Vista Print Signed Up 5,000 Subscribers in 60 Days

Have you considered writing White Papers for your clients, or offering them to your own prospective customers as a lead-generating device? If you operate in a technical field, I think you should definitely consider a White Paper. You can either write one ourself or have someone else write it for you.

Akinci, Ugur. Technical Communication Center (2009). Articles>Writing>Technical Writing>White Papers

The Cardinal Rule of Interviewing a Subject Matter Expert (SME) For a Document

A technical writer will periodically need to interview Subject Matter Experts (SME) to gather information about a technical document. More often that not, and especially within the context of software development, most SMEs are engineers and software developers. But they can also be mechanical, electrical and other types of engineers, hardware installers, network engineers, testers, site foremen, call center engineers, field technicians, sales or marketing people, local dealers, etc. One cardinal rule of interviewing an SME is to do your homework well, in advance.

Akinci, Ugur. Technical Communication Center (2009). Articles>Interviewing>Technical Writing>SMEs

How to Format Your Technical Documents Consistently With a Template

Consistency of a technical documentation is what creates that subliminal sense of trust and confidence in the end-users. Someone once quipped: “it ain’t technical documentation if it ain’t boring.” This of course is not true since I always found technical documents very interesting indeed. I’m the sort of geekish person who can marvel at a well-designed user’s manual for hours and appreciate its beauty and all the effort and thinking that went into its production. I imagine how happy people would be when they use that manual and solve their problems and that, believe it or not, makes me happy as well. That’s the main reason why I’m in this business.

Akinci, Ugur. Technical Communication Center (2009). Articles>Document Design>Style Sheets>Technical Writing

How to Comply With Moral and Ethical Standards in Technical Documentation

Technical writing has a number of moral and ethical standards that a professional technical writer needs to comply with. Violate them at your own peril, by risking the sudden demise of your career. Here are some of these issues.

Akinci, Ugur. Technical Communication Center (2009). Articles>Documentation>Technical Writing>Ethics

Top 3 Open Source Software You Can Use to Write and Design Technical Documents

Although I love using the proprietary software that I’ve mentioned in the first sentence, I enjoy using open source software as well since some of them are actually better than the paid software in some respects.

Akinci, Ugur. Technical Communication Center (2009). Articles>Software>Technical Writing>Open Source

Wurman’s LATCH Model of Information Organization For Technical Documentation

Technical writing has its mechanical aspects that need to be mastered. A good technical writer must know how to use English effectively as well as various software products to produce acceptable technical documents. But I wish technical writing were all about that. The hardest part comes before one even sits down in front of a computer to type the first word. The hardest part in documenting anything is organizing the information in a way that makes sense from the user’s point of view. Otherwise a technical document suddenly looks irrelevant.

Akinci, Ugur. Technical Communication Center (2009). Articles>Information Design>Documentation>Technical Writing

How to Structure FrameMaker Paragraphs While Using the Unstructured Interface

Using the structured features requires advanced training and you probably won’t need them anyways unless you’re doing any “single sourcing” (which is the topic of yet another article). For example if you were doing any XML-based authoring or “database publishing” then you would definitely need to learn how to use the FrameMaker’s structured interface. However, there is an easy way to imitate structured documentation while you are still in the unstructured mode. This is one case in which you can have your cake (unstructured FM) and take a bite out of it too (by enjoying one selected feature of structured documentation).

Akinci, Ugur. Technical Communication Center (2009). Articles>Document Design>Technical Writing>Adobe FrameMaker

Seven Time-Tested Principles to Design a Cover For a Technical Document

Here are seven time-tested design recommendations culled from my 20 years of experience as a professional writer, page layout and information designer.

Akinci, Ugur. Technical Communication Center (2008). Articles>Document Design>Technical Writing

Advantages of Using Microsoft SourceSafe While Writing Your Technical Documents

Microsoft’s Visual SourceSafe was not created with technical communicators in mind. It was created for engineers writing software source code. But it is successfully used by technical writers in offices around the world to control documentation.

Technical Communication Center (2009). Articles>Content Management>Documentation>Technical Writing

Seven Top Web Writing Principles For Technical Writers

Web writing is one of those assignments that technical writers do well due to their organized approach to technical information. But web writing differs from regular user guide and procedural writing in some important respects. The Web is a fast place. People usually don’t have the time to go through long essays.

Technical Communication Center (2009). Articles>Web Design>Writing>Technical Writing

When Should You Definitely Use Jargon in a Technical Document?

As a technical writer you’ve heard this piece of sage writing advice a thousand times: you should stay away from jargon and write as you speak. It’s basic. Strunk & White said so, didn’t they? It’s true. But is this rule true ALL the time, unconditionally? No, I’m afraid it is not. Life has its exceptions. And so does this “rule.”

Akinci, Ugur. Technical Communication Center (2009). Articles>Writing>Diction>Technical Writing

Technical Writing for the Terrified

Technical writing unsurprisingly enough, refers to writing that is technical. Although this may seem like a fallacious definition, it’s an important one to remember. Too many technical authors make the mistake of creating documentation that is either too technical, or too ‘literary’. A good technical author should be able to adjust the balance between the two to suit the end user of the documentation. Technical writing is a lot like fresh air, pervasive and yet pretty much invisible. In the weird wired world in which we find ourselves, technical writing is everywhere. Software manuals, user guides for home appliances, instructional leaflets, emails, letters, reports, technical news reports, statistics and biographies on television sports shows all are examples of technical writing to which people are exposed to on a daily basis. If you have ever tried to program the time settings on a home video recorder and flung the manual across the room in disgust, you threw a piece of technical writing (although obviously not a very good one!).

Daily Blogging Spot (2009). Articles>Writing>Technical Writing

How to Use the Bulleted Lists Properly in Your Technical Document?

Bulleted lists are important in technical writing. They summarize information in a manner that is easy to read and absorb. Use them whenever you can to get your information across quickly. Bullets are ideal for things-to-do, equipment, sets, collections, cooking ingredients, and all kinds of other lists.

Akinci, Ugur. Technical Communication Center (2009). Articles>Documentation>Style Guides>Technical Writing

Issues in Medical Writing

There is no doubt that medical communications is a very young field. The clearest picture of the issues, problems, and needs of a discourse community with as complex a membership as that of medical communicators comes from the AMWA materials. Drawing boundaries between academic vs. medical professional vs. medical communicator seems pointless because of the nature of the medical communication. It also seems to be an area ripe for study by those interested in power issues in rhetoric and certainly in research in communication systems. Medical communication really is both the most and least specialized area of technical communication.

Taaffe, Maura. Michigan Tech University (1998). Articles>Writing>Technical Writing>Biomedical

Structured Authoring for Everyone

While the concepts of structured authoring are more than just slightly useful for technical writing, they can be beneficial for just about any writing task within an organization. But how do you bring XML-based structured authoring to the masses? Perhaps by taking a cue from a word processor called Yeah Write.

Nesbitt, Scott. DMN Communications (2009). Articles>Documentation>XML>Technical Writing

David Pogue's Secret Weapon: Patience

New York Times gadget guy David Pogue, a former Broadway orchestra conductor and MacWorld back-page columnist, is probably the world's most widely read and watched tech product reviewer. As a fellow contributor to the Times, I can confirm that anything Pogue writes pulls down several times as many page views as my most popular work. How does he do it?

Boutin, Paul. Industry Standard (2009). Articles>Technology>Writing>Technical Writing

Designing Websites

The parallels between the theories of technical communications and those of web design are very similar, the key aim is to keep the audience in mind at all times. The way you structure and present the information is also important, as is a sense of usability of the content itself.

McLean, Gordon. One Man Writes (2009). Articles>Web Design>Technical Writing>User Centered Design

How to Avoid Unnecessary Granularity

The more skilled and experienced the readers are, the more they hate to be told in minute detail what to do. The more skilled and experienced the readers are, the more they like Checklists instead of detailed procedural steps.

Akinci, Ugur. Technical Communication Center (2009). Articles>Writing>Technical Writing

Technical and Copy Writing: How to Use Causality Correctly

Organize your writing so that it becomes very clear what kind of cause-and-effect relationship exists between different elements of your argument.

Technical Communication Center (2008). Articles>Writing>Diction>Technical Writing

Technical and Copy Writing: How to Write “Hamburger Emails”

You can use the “Hamburger Paradigm” of writing not only for technical articles and copy but for other types of communications as well, ranging from emails to criticism.

Technical Communication Center (2009). Articles>Writing>Technical Writing

Where Did All the Documentation Go?

Documentation is a huge cost factor in software development, and companies are looking for ways to trim costs. If you cut back on product doc and customers don't complain, there's a temptation to keep cutting. Eventually you end up with software engineers writing bits of doc because all the tech writers were laid off, but there'll be one guy who didn't get laid off who has to work like heck to wire it all up and make it continue to look like professionally written doc.

assertTrue (2009). Articles>Documentation>Programming>Technical Writing