Browsing articles tagged with " information typing"

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
organization.

  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.

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:

Saiff Solutions In The Media

- TechWhirl
- Nominated for 2015 Rice Bowl Asean Start Up

Click image to enlarge

Testimonials

“Barry [Saiff] has extensive experience both as a manager of technical writers and as a writer. As a manager, he is fair, encourages innovation, and is open to divergent points of view. As a writer, he can grasp very complex concepts and explain those concepts to end user through administrator audiences. Additionally, he has expert knowledge of all components of the documentation process, including corporate style guides, editing, writing, working with localization, and production. Barry is very much a people person and wherever he goes, he cultivates a large network of friendly yet professional relationships. He’s worked successfully with both on-site subject matter experts as well as those across the world. During my time working with Barry, he’s run a number of successful efforts to improve the usability of documentation. In one such case, he recruited a cross-functional team to overhaul the documentation based on the recommendations of this user-facing group of subject matter experts.”

Steve Anderson
Principal Technical Writer, Symantec
December 16, 2010

Read more testimonials here.