Browsing articles tagged with "process topics Archives | Saiff Solutions"

The 7 Habits of Highly Effective Technical Communications Leaders

Oct 5, 2016   //   by Christian Cahapin   //   Blog, Evaluating Technical Writers, How-To, Managing Technical Writers  //  No Comments


You can be an effective leader, regardless of your position. These 7 habits go beyond the basics of developing good content, to answer this question:

As a technical communications leader, at any level, how do you influence the work environment, improve the processes, and educate the people to make continuous improvement possible?

1. Be a Customer Advocate

be-a-customer-advocateWhile you may have less product knowledge than an engineer, you can view the product from a user’s perspective. Share your input and advocate for product and process improvements. Support similar efforts initiated by others. Focus on quality.

2. Advocate for Process Improvementsadvocate-for-process-improvements

Process improvements can benefit everyone on the team, and improve product quality. Can the quality assurance team test the documentation? Can technical writers edit the user interface text and error messages? Can written documentation reviews become a factor in the performance evaluations of all product team members? Would documentation review meetings improve quality?

3. Care About All Customer-visible Content

If you’re only writing the customer documentation, there is a chance that no one with your skills is editing other user-visible content. Even if you cannot edit this content, you can educate others about key technical writing practices. For example – One concept, One term – each word should be used to mean only one thing. This avoids user confusion, and saves translation funds. Another key technical writing practice: short sentences.

4. Be an Effective Intrapreneurbe-an-effective-intrapreneur

Think about how to create change – look before you leap. Understand the who, what, and how of change. Who are the key stakeholders and decision-makers, and what motivates them? What do they care about? How can you best bring them on board? What are their backgrounds – cultural, professional, educational? Start with curiosity. Listen. Discuss. Ask questions.

5. Know Your Audience

know-your-audienceWhat do you know about the users – education levels, roles? How do they use the product and access the documentation? What percentage read the documentation in English? Collaborative efforts with other teams can aid your research. One way to learn more is to conduct a user survey. While gaining approval can be an uphill battle, the insights gained from a well-designed survey can make the effort worthwhile.

6. Promote Appropriate Technical Communications Methodologies Gentlypromote-appropriate-technical-communications-methodologies-gently

Not every organization needs to use the latest methodologies. What worked elsewhere may not work for your team. Bring others along with you – educate and involve engineers, quality assurance personnel, marketers, and product managers in assessing and exploring new methodologies. For example, some organizations can benefit from adopting topic-based authoring, without XML or DITA.

7. Keep Perspective, and De-stress

keep-perspective-and-destressMistakes provide tremendous opportunities for personal and organizational growth, including improved processes, communications, and skills. Accept these moments and make the most of them. Learn from successes and failures. Remember that what is truly irreplaceable is human life. Learn what you need, and what your coworkers need, to reduce and relieve stress.

Consistently practicing these 7 habits will support your development as an effective technical communications leader, continuous process improvement in your organization, harmonious work relationships, and improved content and product quality. Be the change you wish to see.

You may also like:

2016 New Year’s Gifts

Happy New Year from Saiff Solutions!

Please accept these presents which we think you’ll find useful for planning a successful year:

2016 calendar with information typing tips

2016 Calendar

Front | Back

2016 planning questions for your team, department, organization


GoalAt Saiff Solutions, Inc., we use these questions every year to support our growth and development.
Feel free to use them to support your own growth and development, as individuals and as an

  1. What did you accomplish in 2015 that you want to be acknowledged for?


1a. How well did you perform on your intentions and promises for 2015?


  1. What did you learn in 2015? (LESSONS LEARNED)


  1. What did you fail to accomplish in 2015?


  1. What is still incomplete for you? Consider your answers above, as well as people, events, or situations that you may be incomplete with.


  1. Are you willing to let it go? If not what do you need to do in order to get complete? By when will you do that?


  1. What is your vision for 12/31/16? Name at least 3 things.


  1. What do you intend to learn in 2016?


  1. What are you grateful for?


  1. What is your greatest challenge?


  1. What support do you need?


Optional bonus questions:

A. Fill in the blanks: I am willing to give up _______________ in order to have _________

B. What are you willing to promise for 2016?

C. What requests do you need to make to get started on fulfilling your promises and your vision?

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.

Saiff Solutions In The Media

- TechWhirl
- Nominated for 2015 Rice Bowl Asean Start Up

Click image to enlarge


“Barry [Saiff] is one of those people that every company needs. He is a very efficient and productive member of any team and on top of that ensures that others feel a member of the team also. Whilst at Brightmail I got to know Barry as he was the organizer for our local toastmasters group. His energy and enthusiam encouraged this collection of diverse people to create a wonderful group experience. I would recommend Barry for any position that required trust, loyalty and a great sense of humor.”

Raj Rana
Sr Systems Engineer, Brightmail
December 27, 2010

Read more testimonials here.