Browsing articles in "Blog"

Why Do We Need Good Technical Writers?

Mar 12, 2014   //   by Barry Saiff   //   Blog, Reference Articles  //  1 Comment

And what do technical writers do, anyway?

Have you ever asked, or been asked why you need good technical writers?

The answer:
Developing quality documentation that effectively addresses the needs of each user, without overwhelming them with information they don’t need, is a skill that takes years to develop. It differs fundamentally from other forms of writing used in marketing, engineering, testing, or product management.

Penny-wise and Pound Foolish?

In a real-life example at a large company, the IT Team needed to make an immediate change to the VPN (Virtual Private Network) login procedure. This change would affect thousands of employees who logged in daily. To save precious time and money, the IT Manager asked an IT Engineer to write an email explaining the new login procedure, instead of using the Documentation Team.

Do you agree with the IT Manager’s decision? The result suggests it was not the best approach: The Helpdesk Team received over 10,000 support calls from employees who had problems logging in, ultimately costing the company thousands of dollars in technical support time.

The IT Manager learned some fundamental truths:

  • Good product documentation reduces support costs.
  • Not all engineers are also good technical writers.
  • The cost of hiring a good technical writer in many cases pays for itself many times over.

What Do Technical Writers Do?

Let’s look at how a technical writer works. What does a technical writer do when faced with a new project? Here are five of the most basic steps.

Step 1: Learn about the product

The first step is to gather background about the project or product. What needs does this technology address? What is the purpose of the product?

Step 2: Identify Your Audiences

Who uses this product? What are their roles, education, and work experience? Make a list of your user types, for example:

  • User 1 – Database administrator: technical degree, manages databases.
  • User 2 – Loan officer: experienced computer user, finance professional, approves loans.
  • User 3 – Executive: computer user, focused on reporting features.

Step 3: Start Counting — Features

One thing a technical writer does at the start of a project is count. Two of the most important things to count are features and tasks.
To count features, consider:

  • How many pages does the user interface contain?
  • How many elements or controls on each page?
  • How many total elements, on all pages, menus, etc.?

You don’t need a complete list. Just make some initial notes, for example:

  • Main pages: 8
  • Sub-pages, dialog boxes: 11
  • Elements per main page: average 12
  • Elements per sub-page or dialog box: average 8

Total elements: 184

Step 4: Begin Task Analysis

What tasks must a user accomplish? Each task includes a list of steps. Each step is a single action. Start a list of tasks, for example:

  • Add borrower
  • Add loan source
  • Configure borrower options
  • Configure regions
  • Configure global options

Step 5: Putting it Together

Consider the users you identified. To complete these tasks, what will they need to know?

Good product documentation requires topics, or chunks of information, of at least three types: task, reference, and concept. For a description of each type, see http://saiffsolutions.com/home/topic-types.

You’ve made a good start. Answering these questions enables you to start answering others, such as:

  • How many task, reference, and concept topics do I need?
  • What information is important to each type of user?
  • How can I organize the documentation so that all users find what they need quickly?
  • How long will it take to complete the documentation?

What About Apps?

You may be thinking, “This seems like a lot of work! Is all this needed for two sentences to explain a mobile app?”

While some apps are very simple, others are not. A sentence or two may suffice for one page or function. A complex app will require quite a few sentences.

And, as Mark Twain said, “I didn’t have time to write a short letter, so I wrote a long one instead.”

Writing fewer words with equal effectiveness takes more skill and more time.

What is the Value of a Good Technical Writer?

Doing this type of analysis repeatedly enables a technical writer to notice things that even an engineer who developed the product may miss. Good technical writers have years of experience writing, rewriting, and then rewriting again to eliminate unnecessary words.

Why do we need good technical writers? Let us count the ways:

  • To create accurate, concise documentation that enables users to complete tasks independently.
  • To organize information so that users quickly find what they need.
  • To avoid confusing users with extraneous or out-of-place information.
  • To avoid losing users due to inappropriate assumptions about their knowledge and background.
  • To reduce support costs.
  • To increase customer satisfaction.
  • To demonstrate to customers that the guidance they need is accessible and easy to use.

Of course, as with every profession, there are both highly competent and less competent technical writers. At Saiff Solutions, we have decades of experience in hiring and managing outstanding technical writers. Because we are located in the Philippines, where English is the primary business language yet labor costs are much lower than in the U.S., we are able to offer the best value on the planet in technical writing services.

Is there something we can help you with?http://saiffsolutions.com/home/

Barry2014012c

Topic Types

Jan 6, 2012   //   by Barry Saiff   //   Blog, Concepts and Definitions, Reference Articles  //  No Comments

Hang on!  Before reading further, we just wanted you to know that this post is related to the previous.

Task Topics contain a procedure, represented by a list of numbered steps. The title of a task topic names the task. After the title, a few introductory sentences introduce the procedure by answering questions such as:

  • Why should I perform this task?
  • What do I need to do before performing this task?
  • What can I do after performing this task?
  • What problems might occur if I perform this task?

After the introductory material, a one-line lead-in introduces the procedure. A list of numbered steps follows. Each number is followed by only one sentence, which instructs the user to do something. Any additional material needed for that task is provided in a separate, indented paragraph under the numbered step. Some of these paragraphs can be links to other topics.

Here is an example of a task topic that explains how to write a task topic:

[Title] Writing a task topic

[Introduction]A task topic includes a procedure, consisting of a numbered list of steps. A limited amount of introductory material precedes the procedure. The procedure itself provides only the information essential for performing the task. In some cases, you can provide a link to relevant information, instead of cluttering up the procedure with reference or conceptual information.

[Lead-in] How to write a task topic:

  1. Write a title for the topic that includes a gerund (a word ending in “ing”), and describes the task documented.
  2. Write an introduction for the topic that explains the context of the task.  Mention any restrictions on performing the task.
  3. Write a lead-in sentence that begins with “How to” and matches the title.  End the lead-in sentence with a colon. The lead-in sentence is usually not a complete sentence (see example above).
  4. Write the numbered steps for the procedure.

The first paragraph of a numbered step contains only one sentence. That sentence instructs the reader to do something. Additional information is provided in separate paragraphs indented below the numbered paragraph. Keep the additional information minimal.

By not mixing, for example, task and concept information in the same topic, you gain several advantages:

  • A reader who just wants to know how to do a task does not need to wade through conceptual information to find the procedure she needs.
  • If you choose to present all the procedures together in a special document, you don’t need to separate out conceptual information.
  • You can easily provide all the task topics to the team that will test the procedural documentation.
  • By including links to the most relevant concept and reference topics in each task topic, you can direct the reader who is interested to useful information without cluttering up the procedure for the reader who doesn’t need that information.

Reference Topics contain reference material. Reference material may be necessary to perform tasks or to understand technology. Reference topics often contain tables of information. For example, lists of parameters and their corresponding values or impacts. A table of types of mortgages and the requirements for each type. A table of features, showing which features are available from the product’s graphical user interface (GUI), and which features are available from the command line interface.

Concept Topics provide background and explanation. Even if it is necessary for the reader to understand quite a bit of background information before performing a task, do not include all of the information in the task topic. Instead, include a link to one or more concept topics that provide the necessary background. For example, an explanation of each type of mortgage and its history belongs in a concept topic, not in the midst of a procedure for choosing the mortgage type.

Process Topics describe complex processes that consist of multiple tasks, each of which consists of multiple steps. A process topic typically contains a table. Each row in the table represents one task, and provides a link to that task topic.

Process topics can document any of the three basic types of processes:

  • Linear. In a linear process, a set number of tasks must be performed in a specific order, without variation.
  • Branching. A branching process contains one or more decision points. At each decision point the reader can choose from two or more “branches” or alternate paths through the process.
  • Circular. After completing a circular process, the user can continue to perform the same tasks again. Some circular processes can be started at any point in the circle.

The process topic shows the sequence of steps, and indicates any decision points where the sequence may branch, or become circular. A process topic may contain a flow diagram, that documents the process flow. Flow diagrams can be particularly useful for branching and circular processes.

Online Help Topics typically contain a table that lists controls, commands, or features of an interface or product. These topics are accessible from within the product interface. If the topic contains information specific to the interface location from which it is accessed, it is called a context-sensitive topic.

Context-sensitive help topics often list all the controls available on a specific page or screen of the user interface, documenting each control, and provide links to relevant task, concept, and reference topics. Depending on your content strategy, you may choose to also provide procedures in the online help topics themselves, rather than linking to task topics.

Information Typing

Dec 30, 2011   //   by Barry Saiff   //   Blog, Concepts and Definitions, How-To, Reference Articles  //  No Comments
OK, I understand that topic-based authoring is crucial to being able to reuse topics in different contexts, so that I can make available to each user the documentation they need on the device they use. What about topic types? Where do they fit in, and why do they matter?

Information typing provides the answer. Successful topic-based authoring depends on information typing. Each topic must have a type. The topic should only include information consistent with its topic type.

All topics share the following characteristics:

  1. The topic begins with a title that concisely described the information contained in the topic.
  2. The topic is stand-alone. That is, the topic can be understood without reference to other topics or documents.
  3. The topic contains references or links to other relevant topics.

Note that characteristics 2 and 3 are not contradictory. State-of-the-art product documentation has left behind the assumption that all readers will read every book in the order in which it is presented. If each topic stands alone and can be understood by itself, yet links to other relevant topics, the reader is empowered to choose the order in which he consumes the content. This is a more effective approach because many readers will pick and choose, even if they are instructed otherwise.
For product documentation, nearly all the information needed can be classified into one of the following basic topic types:

Two additional topic types are actually special types of reference topics:

Types of writing

Dec 19, 2011   //   by Barry Saiff   //   Blog, Concepts and Definitions, Reference Articles  //  1 Comment
What is Technical Writing?

What is technical writing? Common usage differs in different places and contexts. In some universities in the Philippines, courses that teach how to properly write business correspondence and reports are called technical writing courses. This usage differs from the definitions below.

Business writing includes all types of non-fiction writing that may be needed to support a business. However, business writing refers most often to business correspondence, both internal memos and business letters, and business presentations, reports, and similar documents. Business writing also includes marketing writing.

Technical writing is writing that deals with technical subject matter. This includes training materials and all types of product documentation. Technical writing often refers mainly to software documentation. While technical writing is a subset of business writing, technical writing can occur in non-business environments, such as universities, non-profits, and government agencies. Technical writing often includes marketing writing. Technical writing also includes various specialized types of writing, for example aerospace, medical, legal, and scientific writing.

Marketing writing includes any writing intended primarily to represent a product or an enterprise to its market. For example, brochures, data sheets, white papers, and Web sites.

Of course there is a good deal of overlap between these categories. Web sites often provide product documentation and other technical material. White papers may be more technical or more marketing-focused. A business proposal for a product may be full of details about the technology of the product.

Just in the USA, there are approximately 20,000 technical writers, of whom at least several thousand are writing software documentation. It is likely that many millions of other workers in the USA are engaged in business writing during at least part of their work days.

The definitions here are important because of the confusion between business writing and technical writing that appears to be prevalent in the Philippines, and perhaps in other countries as well.

Pages:«123456

Saiff Solutions In The Media

- TechWhirl
- Nominated for 2015 Rice Bowl Asean Start Up

Click image to enlarge

Testimonials

“Barry [Saiff] truly is a force of nature – he is a consummate professional with deep technical expertise when it comes to technical writing which lets him just “get it” right out of the box. Barry pairs very strong writing skills with the ability to easily speak both “business analyst” and “software engineer” in the same meeting. Barry was the lead information developer for my product at Symantec, and I had the utmost confidence in his abilities and work ethic. On top of all that, Barry has a wonderful sense of humor and an infectious laugh that can transform the work environment in an instance. I strongly endorse Barry’s many talents and would welcome working with him again in the future.”

Angelos Kottas
Principal Product Manager, Symantec
December 17, 2010

Read more testimonials here.