Technical Writing
Perseverance vs. Perseveration and the Role of Stress in Writing Life
© Ugur Akinci I have always wondered about the relative merits of hanging in there and keep pushing up against life’s obstacles (perseverance), on the one hand, and continuing to do what clearly does not work and suffering the inevitable consequences of uncontrollable repetition (perseveration), on the other. The dominant market mentality encourages us to…
Read MoreBook Review: Conversation and Community by Anne Gentle
Anne Gentle, senior technical writer and author of the JustWriteClick blog, has just published her first book: Conversation and Community: The Social Web for Documentation. Anne graciously sent me a copy, and I’ve put together the following review. The major premise of this book is that expectations for documentation have shifted from bookshelf to search.…
Read MoreA Reader Question: "How should we test the quality of a User Guide?"
Testing the quality of a user guide is a topic not addressed too frequently. I have received the following inquiry from a regular reader of mine: QUESTION: “I would like your opinion on how do you or your company ensure that only complete and quality documentation is delivered to the customers. I am asking this…
Read MoreThe Importance of Using the Right Words
© 2009 Ugur Akinci Using the right words is so critical in communications in general and technical writing in particular. The wrong word can take the conversation to a totally unintended direction, sometimes with humorous and other times with not-so-humorous results. Here is an example… As I was jogging the other day I was listening…
Read MoreA Great Manual from Open Office: "Creating Large Documents"
The free writing suite Open Office has come up with a great free PDF document that should be of great help for all writers generating long (over 50 pages) documents. (I’d like to thank my reader George L. for bringing this free resource to my attention.) The 48-page “Creating Large Documents” is written in an…
Read MoreDo Your Verbs Agree with Your Subjects?
© 2009-2010 Ugur Akinci It’s a fundamental rule of English grammar: your VERB must agree with the SUBJECT of your sentence. Why I’m addressing this very basic rule? The reason is, when violated, it can have disastrous consequences in technical writing. First the RULE: The garage [Main SUBJECT] where he kept [auxiliary VERB] his antique…
Read MoreSharing Content – Can It Hurt Your Web Site Traffic?
© 2010 Ugur Akinci Can sharing content “too much” be a problem for your web site traffic? I admit, I had this paranoia about sharing “too much” information with my visitors years ago but not any more. Because the more you share, the more your readers will accept you as an authority in your field,…
Read MoreHow much should you charge as a writer?
The question of “how much to charge” is always up in the air. I personally try not to quote an hourly rate and much rather work for a set fee. That avoids any second guessing on the part of the client as to how many hours any job “should take.” Having said that, here is…
Read MoreWhich Way Your Sentences Branch – Right or Left?
Ugur Akinci Try right-branching sentences in your technical documents for higher comprehension. Right-branching sentences start with the SUBJECT, follow it with PRIMARY VERB (or sometimes the other way around if the verb is in imperative/order mode), and then end with modifiers and other relevant information. What branches off to the right of the subject and…
Read MoreWhat a Technical Writer Should Know About DocBook?
© 2009 Ugur Akinci DocBook is a set of tools for implementing XML (Extended Markup Language)-based structured documentation. It is developed back in 1991 and is widely used today by those technical writers who generate single-sourced documentation. It is especially well suited for software, hardware and networking documentation. A DocBook set includes the DocBook DTD…
Read More