Archive for June 2010
Technical Book Review – THE COMPASS: Essential Reading About XML, DITA, and Web 2.0
© 2010 Ugur Akinci Here is a mighty little volume by Scriptorium.com that should be mandatory reading for all those either brand new to structured authoring or looking for technical details about DITA (Darwin Information Typing Architecture) OT (Open Toolkit) and PDF generation. The last chapter on “Web 2.0 in Technical Communication” is also good…
Read MoreHow to Make Sure Stakeholders Read your Software Requirements Specifications (SRS)
© 2010 Ugur Akinci It’s a rather common predicament — a technical writer or Product Manager sits down and after months of labor finishes writing a comprehensive Software Requirements Specifications (SRS) document, or “specs” for short. And then… SRS falls through the cracks and is forgotten, not because of ill-will on anybody’s part but because…
Read MoreWrite Your Technical Documents in Consistent Case
© 2010 Ugur Akinci The verbs you use in your technical writing must agrees with the case of your subject(s). For example: The school [Main SUBJECT] where he graduated [auxiliary VERB] from is [Main VERB] the oldest in the country. (School [singular] … is [third person singular]) VIOLATION of the rule: The school where he…
Read MoreDid You Know these FrameMaker Facts?
© 2010 Ugur Akinci I love FrameMaker. I’ve been using it on an almost daily basis for the last 12 years. It’s my authoring and publishing tool of reference for all book-length manuscripts with images, tables, TOC, Index, and multiple lists (of tables, figures, etc.), and complex pagination. It’s solid, scalable without any worries, and…
Read MoreWrite Your Technical Documents with Consistent Voice and Mood
Technical writing is consistent writing, whether you’re writing software or marketing specs. Your sentences need to be consistent in Voice Mood Case Tense Style If you end your sentences with the same mood, voice and tense that you start them with, the battle is already won. [Which rule did this sentence violate already?] Technique 1)…
Read MoreUse Parallel Construction in Technical Writing, whenever possible
© 2010 Ugur Akinci Try to write in sentences that have similar syntaxes and components. Construct your sentences and paragraphs with “parallel,” i.e. similar, components. That increases audience comprehension and retention. It makes your technical documents more user-friendly. For example, if you start the first sentence in a procedural description with an action verb, start…
Read MoreSouth Dakota — Black Hills State University Offers Corporate Communication B.S. Degree
BROOKINGS, S.D. – The South Dakota Board of Regents Thursday approved a new undergraduate degree in corporate communication at Black Hills State University. It also authorized the university to deliver its existing mass communication degree to students in Rapid City. “In today’s business world, it is more important than ever to prepare effective communicators,” said…
Read MoreEliminate "Variance" from Your Technical Writing
© 2010 Ugur Akinci “Variance” is an important concept in statistics and plays a crucial role in technical documentation as well. Without getting too technical about it: “variance” denotes the way the values of a set of elements vary around a central mean value. Imagine you weighing a hundred marbles. Let’s say the arithmetic-mean weight…
Read MoreMaking the Transition from Technical Communication to Customer Experience Programme Management
(Excerpts) I’ve been asked quite a bit about my transition from Technical Communications to Customer Experience – what’s the relevance of my skills from my previous role to my new one, what are the surprises, challenges … and so on. People who work in tech comms seem to be surprised by the change; people who…
Read MoreTechnical Writing: Split Long Sentences into Shorter Ones
© 2010 Ugur Akinci Technique: Split long sentences into shorter and simpler ones Here is a sure-fire method to split your long sentences into shorter and more easily understandable ones: Split your sentences at conjunctions like “and”, “or”, “while”, “however”, “although” etc. Those are the connection points where one clause is linked to another. By…
Read More