Chapter 20 Separating Content from Format

1
Chapter 20Separating Content from Format
2
Overview

• For reuse to occur, authors must focus on the
  content's meaning as opposed to its format
• Separating content from format provides your
  organization with ultimate flexibility in how the
  content is used and displayed,both today and into
  the future
• This chapter
• Discusses why it is a good idea to separate
  content from format
• Describes the structured writing principles that
  allow authors to focus primarily on content
• Challenges the belief that for content to be
  effective, authors must know exactly how it will
  be used
• Provides some guidelines for writing the same
  content so it works in different media and for
  different uses

3
Why separate content from format?

• When implementing UCS, it is critical that
  authors structure and write their content
  consistently
• Well-structured content leads to more
  opportunities for reuse across product lines,
  audiences, and information products, greater ROI
• Well-structured content can be reused and used
  effectively
• In traditional environments, authors write the
  content, then format it to accommodate the media
  in which it is being delivered.
• In a unified content strategy, authors are not
  required to format the content stylesheets
  automatically format it based on the contents
  desired context and medium.
• In UCS, authors focus on the information its
  meaning and structure
• Readers get used to reading information in the
  same way

4
Writing Structured Content
5
What is structure?

• What is structure?
• The action of building
• A something that is constructed B something
  arranged in a definite pattern or organization
• Manner of construction
• A the arrangement of particles or parts in a
  substance or body B organization of parts as
  dominated by the general character of the whole
• The aggregate of elements of an entity in their
  relationship to each other
• What is data structure?
• Any or various models of organizing data items in
  a computer

6
What is information structure?

• What is information structure?
• Any of various methods of organizing content in
  an information product
• Manner of construction how content is put
  together
• Arrangement of parts hierarchy of elements
• Aggregate of elements of an entity in their
  relationship to each other how certain elements
  relate to other elements

7
What is structured writing?

• Structured writing is the way pieces of
  information or content are put together to form
  an information product
• Structure is critical in UCS because it unifies
  the content, regardless of who is writing it
• Structured writing is based on information
  theory
• Structured writing is based on cognitive
  psychology
• Structured writing follows standards
• Structured writing applies at numerous levels,
  depending on your need

8
Structured writing is based on cognitive
psychology

• Structured writing is based on how people read,
  process, and understand information
• Principles of cognitive psychology guide us in
  determining how many steps a procedure should
  contain before providing users with a break
• In a structured writing environment, the size of
  a procedure becomes a guideline, or even a rule,
  ensuring the consistency of the procedure for
  both authors and users

9
Structured writing follows standard

• Define standards that focus on meaning rather
  than format
• Create standards for each element, so wherever
  the element appears, it is consistent, and so it
  is also consistent with the other elements
  contained in the information product
• Define standards to identify what content an
  element contains and how it should be put
  together, as well as an example

10
Structured writing follows standard (Cont.)

• Information standards, once defined, are
  consistent
• Once you define the structure of the content (ex.
  Procedure), whoever writes a procedure must
  follow that structure
• The standard tells authors such things as "A step
  must always contain the condition under which the
  step is performed, the action, and the result of
  the action in that order"

11
Structured writing applies at numerous levels,
depending on your needs

• Sentence/step, paragraph, chapter, document,
  volume, set
• The granularity will dictate the level of
  structure you must define
• The more granular your information, the more
  structure you will need, as well as more
  adherence to structure

12
Principles of structured writing

• Chunking
• Each chunk is an independent unit of information
  that can either stand on its own or contribute to
  a larger unit
• People can best hold 5 to 9 chunks of information
  in short-term memory
• Accordingly, structured writing groups
  information into small, manageable units, and
  compiles those units into larger structures, also
  based on the 5-to-9 principle
• Labeling
• Chunks are labeled to identify the type of
  information they contain
• Clear labels make it much easier for users to
  scan for the correct information ("Radio
  Stations" VS. "Tuning your Radio Stations")

13
Principles of structured writing (Cont.)

• Relevance
• Only information that relates to one main point
  is contained in a chunk, eliminating "nice to
  know" information
• If authors want to include "nice to know" or
  "commentary" information, they can include in an
  appropriately labeled chunk, allowing users to
  decide whether it is relevant for them
• Relevance is important from both reuse and
  usability perspectives
• Consistency
• For similar subject matters, use similar words,
  labels, formats, organizations, and sequences
• Consistency is important from both reuse and
  usability perspectives
• When information is presented consistently,
  readers form expectations about what it contains,
  which reduces their learning curves as well as
  their cognitive load

14
Principles of structured writing (Cont.)

• Reuse
• Dictates how a chunk of information can be reused
  in similar information products, so that wherever
  it is repeated, it is the same
• The reuse principle also ensures that when a
  chunk is updated, it is updated in all places it
  appears, guaranteeing ongoing consistency
• Reuse is indicated in the information models (and
  supported by authoring and CM tools), along with
  writing standards that address all the principles
  of structured writing, such as how big that
  element should be (chunking), how it must be
  labeled (labeling), what type of information it
  must contain (relevance), and how it is to be
  structured (consistency)

15
Basing Structure on Information Type

• Chunks of content are assigned "rules" about
  their structure, based on how that chunk will be
  used and the type of information it contains
• Rules are based on the belief that not all
  information is created equally and that it should
  be treated differently
• Ideally, authors consider information types when
  applying the principles of structured writing to
  their content
• How each type is structured is then documented in
  the information model and supported by a style
  sheet that applies a design suitable to the
  information type

16
Basing Structure on Information Type -- Example

• Procedures and processes are best presented in
  sequentially numbered action tables and lists
• Concepts and principles often comprise text-based
  information chunks, with examples and
  illustrations included to support the concept
• Classifications are often presented in lists and
  tables
• Comparisons are best presented in tables that
  directly compare one component with another

17
Authoring and Structure Guidelines for a Warning
18
Applying the Model
19
As described so far in this chapter

• Content must be structured so that it can be
  reused
• Structuring content not only makes it consistent
  for reuse, it also enhances its usability
• The guidelines for creating structured content
  are contained in information models

20
Information Models

• Depending on your need for control and precision
  in your UCS, and on the tools you're using, you
  can provide
• Explicit model guide authors through the process
  of creating structured content (DTD, authoring
  templates, or forms)
• Implicit model written guidelines that authors
  follow manually (instead of being guided by a
  tool)
• Writing according to a model is critical in
  adopting structured writing, because the model
  contains the rules that govern not only what
  elements belong in which information product, but
  also how each element is structured (based on the
  type of information it contains)

21
Purposes of Information Models in Structured
Writing

• Provide guidelines for authors
• Use information models to determine what
  information foes in which information product, as
  well as how to structure each element
• Error codes structure of an error code hints
  or rules about how to write an error code
  examples (best practices)
• Provide guidelines for architects
• Use information models to build the DTD or
  template that authors must follow
• Architects embed information models into the CM
  tools
• Provide guidelines for reviewers
• Model reviewers check information models to
  ensure they support customer and information
  requirements
• Documentation reviewer use models to review
  authors' drafts

22
Reading the Model

• The model would go on to provide writing
  guidelines and an example for each element,
  showing authors such things as how the long
  product description should be structured and
  written, based on the type of information it
  conveys

23
Using the Building Block Approach

• Allow you to identify a core of information that
  is applicable for all information products and
  users, then build on it to customize information
  for different uses and users
• Identify the core information
• Identify what has to be added to the core to meet
  other needs, such as training or different
  audiences
• Tag additional elements according to where they
  belong, e.g., patient guide, programming guide

24
Using the Building Block Approach Example

• Suppose Figure 20.1 is the core
• User guide information
• To the product description, you add
  specifications
• Training materials for the product
• You might add instructions for getting started
  with the product
• Internal staff support materials
• You might add frequently asked questions about
  the product so staff can respond to customers'
  questions

25
Building Blocks for Software Documentation
26
Same Content, Different Use?

• Can the same content really be written so that it
  is appropriate for all its potential uses?
• Content can be reused effectively, simply by
  following writing guidelines that are applicable
  to all the potential uses for the content.
• In addition, the building block approach allows
  for content to be augmented as required, so the
  core is written in a style that is applicable for
  all uses and the augmented parts are written to
  accommodate their specific uses

27
Writing Guidelines for Different Uses

• Well-written online documentation also makes good
  paper documentation and vice versa
• Appendix B "Writing for Multiple Media"

28
Guidelines for Online Documentation and the Web
29
Same Guidelines Applied to Paper
30
Guidelines relate to the principles of structured
writing

• Writing succinctly relates to chunking and
  relevance only relevant content is included in
  "best-size" chunks
• Writing so users can scan is handled through
  labeling, chunking, and relevance
• Layering information is achieved through
  chunking, labeling, and relevance (layering
  according to hierarchy of relevant information)
• Writing user titles is accomplished by following
  the labeling principle
• All guidelines help writers to achieve
  consistently and reusability, especially when
  standards accompany each guideline

31
Example

• The Reo Auto Company is preparing for the annual
  auto show and launch of its new vehicles.
• Launching their first sports utility vehicle
  (SUV) the Tsai.
• Requires a press release to announce their new
  line-up brochures to hand out at the show and
  dealer showrooms updates to the web site and a
  show catalog.
• Three media
• Paper (show catalog, press release, brochure)
• Web (web site, press release)
• Email (press release)

32
Plan

• Show catalog for the entire lineup (photo, short
  description, key features, three cars to a page)
• Brochure for the Tsai only (photo, long
  description with all the features and benefits)
• Press release for the Tsai only (no photo, short
  description, features and benefits)
• Web site for the entire lineup (home page for
  each car with photos, list of full features
  combined with a pricing calculator)

33
Information Models for Tsai Product Description
34
Content Development for Tsai Product Description
35
Content Development for Tsai Product Description
(Cont.)
36
Reusing a product description across multiple
media
37
Reusing a product description across multiple
media
38
Reusing a product description across multiple
media
39
Summary

• Define standards that focus on meaning rather
  than format
• Think about what you want the information to do,
  rather than what you want the information to look
  like
• Create standards for each element, so wherever
  the element appears, it is consistent, and so it
  is also consistent with the other elements
  contained in the information product
• Define standards to identify what content an
  element contains and how it should be put
  together, as well as an example

40
Summary (Cont.)

• Create a writing environment that enables authors
  to structure their content consistently, by
  either supporting them with tools or providing
  comprehensive models for them to follow
• Decide how the elements should appear in their
  various outputs and develop stylesheets that are
  applied when the content is published to its
  various formats
• Following writing guidelines to ensure content is
  written effectively for all media and all uses