The value of technical writing services

Can you prove your worth? What is your impact on a business and how can you quantify the return on investment?

Using recent case studies as examples, Ruth Hamilton and the WritersInc team discuss the value of using technical writing services, and how the return on investment can be described and possibly quantified.

Document Development Life Cycle

Technical Documentation is not just a process of writing. Before the actual content creation starts there are many phases a writer has to pass through.

Just as Software Development Life Cycle (SDLC), technical writing field also has Document Development Life Cycle (DDLC). There are no unique set of stages in a DDLC. Every organization follows a personalized approach for executing their documentation projects. In general, the following list covers most common stages of information development. 

 Documentation Development Life Cycle Phases



Note: This is one of the most common blog posts amongst technical writers. You will get many variants of the same life cycle. I have created this cycle as per my understanding and experience.

Kick-Off: The customer may have an idea about what documents are required for the project even before the software development has started. Alternatively, the customer might not have any idea whether the project needs documentation or not. In either cases, you as a technical documentation expert should have an idea about the scope of the documentation.

Information & Audience Analysis: During this phase, you must gather the useful information of the project and understand all the user documentation requests. It requires a lot interview sessions and surveys to gauge the exact requirements of the project. It is also necessary to understand the readers of your documents. This process is called audience analysis.

Planning & Estimation: After gathering all the necessary information, you can estimate the amount of time and resources required for completing the project during this phase. Based on the estimation, you can devise a feasible plan of execution.

Content Creation: In this stage, you create the content as per the design. But, content creation is not only about writing. It involves other necessary things such as adding relevant illustrations, images, and cross-references.

Review & Testing: Review is one of the most important phases of DDLC. In this phase, your peer (another technical writer or subject matter expert-SME) reviews the content. Generally, it is advisable to follow a “Writer-Developer-SME” approach in review, i.e. first review by writer, second review by developer and the last review by the SME.

Publishing: Once a document is thoroughly reviewed, it can be sent for publication. The same document can be used for various output formats, for example, print (PDF) and online (web help). So, during this phase, you may use as many publication options as per your distribution requirements.

Feedback & Maintenance: This final stage of DDLC ensures that there is a follow up on the documents that are delivered. A proper feedback should also be taken and in case of any discrepancies, you should make sure that the errors are solved and never repeated again.

P.S. In the next few days, I will cover each of these stages as individual topics in detail.

Principles for Effective Technical Communication - 2

You, as a writer should able to understand and anticipate the challenges listed in the previous post.  Your job is to make your users’ tasks easier. So, you can address the challenges using these seven writing guidelines.

7 - Habits of Highly Effective Technical Writer

1. Analyze the subject thoroughly
2. Group information wisely
3. Guide the user and help them find information
4. Elaborate or compress the information scope based on importance
5. Be precise while using words
6. Be crisp and clear with your information
7. Review, review and re-review your information 

1.  Analyze the subject thoroughly.

• Before you start writing a topic, you must have a knowledge base in your mind. You must gather information from existing documents. If possible, you must talk to subject matter experts and study the product extensively.

2.  Group information wisely.

• Group similar topics together
• Each section should be complete and should have an introduction, body and conclusion
• Order the information groups appropriately

            > If you are describing a process, list the steps chronologically

            > To explain something, move from general to specific points
            > To document a project try ordering by problems-methods-solutions
            > To persuade, order your arguments from most to least significant

3.  Guide the user and help them find information.

• Give introduction to let user know what should they expect
• Give summary of what you have covered in the topic
• Use headings, lists, and other formatting devices to make the information accessible.
• Highlight appropriate areas using Note, Tip and Warning statements.

4.  Elaborate or compress the information scope based on importance.

• If you are explaining a complex process involving multiple steps, it is worth adding elaborate steps. Whereas, if you are writing about a commonly used procedure you may write the steps concisely.

Note: Understand your audience before implementing this step.

5.  Be precise while using words.

• Use technical terms correctly and appropriately for the audience. Avoid unnecessary jargon.
• Avoid using vague and ambiguous words
• Avoid lengthy noun phrases
• Avoid using adverbs like actually, apparently, basically, briefly, certainly, clearly, conceivably, confidentially, curiously, evidently, fortunately, hopefully, ironically, etc

6.  Be crisp and clear with your information.

• Avoid wordy phrases: Keep the information simple and understandable. Some wordy phrases might sound "smarter" but they can make documents long and can annoy readers as well. Few examples,

Wordy	Consice
Adequate number of	Enough
At all times	Always
Except when	Unless
For the purpose of	For
In an effort to	To

• Combine short sentences wherever possible. Reconsider breaking a long sentence into short meaningful sentences.
• Generally, favor the active voice over the passive voice. Active sentences are generally shorter and direct. Active voice reduces ambiguity and conveys your message clearly.

   
7.  Review your information repeatedly.

• Review content for errors like formatting, spelling, punctuation, and labels (tables and figures).
• Proofread! Allow some time (even if just a few hours) to pass between drafting and revising the document.
• Edit in parts. Take short breaks while reviewing as well.
• Prepare a checklist based on your review mistakes and observations.

Though, this list is not complete, it  highlights some of the common areas where a technical writer can improve and thereby deliver quality documentation to the customers. For more information on challenges faced by beginners, see Challenges of an Aspiring Technical Writer.

Principles for Effective Technical Communication - 1

You must understand the users of your application well to create documents for them. This post covers the principles required effective communcation.

In the first part, I will demonstrate some of the common errors, we as technical writers make, especially in the beginning of our careers. In the next part, I will list down some of the common principles for effective technical communication.

What annoys the reader?

Vague purpose or context: "What is this write-up trying to convey? How does it fit in the larger picture? "

• You must make sure the information you are providing is not isolated. It should be appear as part of a complete guide or help. Such errors are encountered in topic based authoring.

Confused organization or logic: “Why is the reference appearing before the subject? Why is the flow missing?”

• You must plan your content creation in a logical manner. For example, you may not want to provide explanation about a specific matter before introducing it.

Unclear introductions and conclusions: “I have read this tutorial, now what? What do I achieve reading this?”

• You should clearly define the importance of the written content. You must include appropriate information about the goals in the introduction and conclusion of a topic.

Too much or too less detail: “Why some areas are over emphasized? Why does some content seem peripheral?”

• In no case should a writer try to hide information while writing about a subject. You must make sure that you have gathered enough knowledge about the matter and then prepare content. Simple topics should be explained being less verbose depending on your audience.

Long sentences, jumbled expressions: “Why does this paragraph contain a single line? It is so wordy and time consuming. It has distorted my knowledge on the subject.”

• You must try to write short and meaningful sentences. The reader should be able to make sense of the content at the end of each paragraph.

Improper use of technical terms and concepts: “Why are the jargons misplaced?”

• Do not try to demonstrate your technical expertise in your writing. The content is necessarily prepared for users who want to understand the subject well. So, explain the topic in relatively simple terms.

Writing flaws: “Messy document. The writer should have checked the document for consistency, grammar, etc before shipping. ”

• Bad English or grammar errors can distract a user from the subject. You should recheck your content thoroughly before sending it out to the users.

Though writing is a subjective stream, there are certain facts which remain. You must always take up such challenges from your readers in form of feedback. This will help you to understand the mindset of readers and thus improve your skill set. In the next post, I will demonstrate the 7 habits of highly effective technical writer.

Building your Portfolio - Part 1

Before you go out and start looking for a job as a technical writer, you should be in a position to demonstrate your skills. With the amount of knowledge you have gathered, it is advisable to create a portfolio which helps the employers understand your potential in the field of technical writing.


You can provide various forms of documents in a portfolio, viz. user manuals (steps to solve a particular problem), online help, few technical articles, and video tutorials. This allows the employer to know your versatility and skill set.

There are number of ways in which you can create your portfolio:

Writing help on familiar tasks

You can start building your portfolio writing about familiar tasks like “How to withdraw money from ATM” or “Steps to create a blog”. Utilize your existing knowledge effectively to cover steps required to complete a specific task. Though this is considered a primitive method, writing about known tasks help you in explaining information cleanly.

Working for a non-profit organization

Another effective way of creating a portfolio is volunteering to write for a non-profitable organization. The content you have created can be directly used in a portfolio. Generally, there are no proprietary information issues, but it is still recommended that you get a confirmation from the organization.

Writing help for mobile app

With the advent of smart phones, there is a large mobile application database on the internet. For most of these apps, there is not much help available. Though, these applications are relatively simpler to use, you can still create help for them and demonstrate your skills. It is surely a nice value add to your portfolio.

In addition to the above methods, learn technical documentation tools that facilitate content creation and publishing your documents. To know more about the list of documentation tools available, see Technical Writers toolbox.

The best way to learn a tool is to download its trial version. There are a lot of online resources available over the internet. You can learn and use these tools to generate PDF and HTML output for your portfolio. Such portfolios have multiple advantages as they demonstrate your ability in content creation as well as tools.

The next post covers creating your blog or website as a portfolio.