• Share
  • Email
  • Embed
  • Like
  • Save
  • Private Content
Topic based and structured authoring - slides
 

Topic based and structured authoring - slides

on

  • 3,755 views

Slides from topic-based/structured authoring workshop at Lavacon

Slides from topic-based/structured authoring workshop at Lavacon

Statistics

Views

Total Views
3,755
Views on SlideShare
3,738
Embed Views
17

Actions

Likes
0
Downloads
67
Comments
0

1 Embed 17

http://www.scoop.it 17

Accessibility

Categories

Upload Details

Uploaded via as Microsoft PowerPoint

Usage Rights

© All Rights Reserved

Report content

Flagged as inappropriate Flag as inappropriate
Flag as inappropriate

Select your reason for flagging this presentation as inappropriate.

Cancel
  • Full Name Full Name Comment goes here.
    Are you sure you want to
    Your message goes here
    Processing…
Post Comment
Edit your comment
  • 1
  • 5
  • 7
  • 17
  • 7
  • 7
  • 17
  • 2
  • 2
  • 2
  • 2
  • 2
  • 17
  • 2
  • 7
  • 17
  • 5
  • 7
  • 7
  • 5
  • 5
  • 5
  • 2
  • 5
  • 5
  • 5
  • 7
  • 17
  • 2
  • 2
  • 2
  • 2
  • 2
  • 17
  • 7
  • 7
  • 2
  • 2
  • 7
  • 2
  • 7
  • 7
  • 15
  • 15
  • 7
  • 7
  • 5
  • 5
  • 2
  • 7
  • 7
  • 7
  • 7
  • 7
  • 7
  • 7
  • 2
  • 2
  • 5
  • 2
  • 5
  • 5
  • 5
  • 5
  • 5
  • 5
  • 7
  • 7
  • 2
  • 7
  • 7
  • 7
  • 7
  • 7
  • 7
  • 7
  • 7
  • 2
  • 7
  • 7
  • 2
  • 7
  • 2
  • 7
  • 7
  • 7
  • 7
  • 7
  • 7
  • 7
  • 2
  • 2
  • 2
  • 2
  • 2
  • 7
  • 7
  • 2
  • 2
  • 2
  • 2
  • 2
  • 2
  • 7
  • 7
  • 7
  • 7
  • 7
  • 7
  • 7
  • 7
  • 7
  • 7
  • 7
  • 7
  • 2
  • 7
  • 2
  • 2
  • 7
  • 7
  • 7

Topic based and structured authoring - slides Topic based and structured authoring - slides Presentation Transcript

  • Topic-Based and Structured Authoring
  • Who Am I?
    • Neil Perlin - Hyper/Word Services.
      • In tech. comm. since ‘79 at DEC.
      • Creating hypertext since ’85, WinHelp since ’90, HTML since ‘91.
      • Training and consulting on HATs since ’95, XML, mobile devices, single-sourcing, structured authoring since ‘98.
      • STC’s lead W3C rep – ’02 – ‘05.
      • Certified in Flare, RoboHelp, Captivate, Mimic, others now gone.
  • Contents
    • 1 – Definitions
    • 2 – Rationales for Use
    • 3 – Strategy and Tactics
    • 4 – Hands-On Practice
  • Section 1: Definitions
    • Introduction
    • What’s Topic-Based Authoring?
    • What’s Structured Authoring?
    • Introduction
  • Workshop Goals
    • Understand topic-based and structured authoring concepts to:
      • Decide whether they make sense for you.
      • Understand their larger context.
      • Implement them without turning your world totally upside-down.
  • Workshop Philosophy and Caution
    • Not to immediately jump to a standard or tool.
    • Instead, make decisions deliberately.
      • Avoid the “there’s never enough time to do it right but there should be time to go back and fix it later” approach.
    • Avoid paralysis by over-analysis.
    • Anticipate a continuing, often messy effort.
    • What Is Topic-Based Authoring?
  • What Is Topic-Based Authoring?
    • Authoring content in the form of topics rather than documents or books.
    • Trendy because of single sourcing and DITA, but not new.
      • Arose in 1991 with Doc-To-Help.
      • Or even in 1965 with InfoMapping.
  • What’s a Topic?
    • As focused and self-contained as possible a discussion about a single subject.
      • Focused – Answers one question – “How do I…?”, “What is…?”, etc.
        • Is this DITA? Can be , but doesn’t have to be .
      • Self-contained – Contains all info needed to answer the question.
        • Related info is in separate topics.
        • Each topic links to the related but separate topics.
  • What’s a Topic? (cont’d)
    • Example – Info to fix a broken window…
      • Put steps in one topic…
      • Information about glass-making in another…
      • A list of standard pane sizes in another…
      • How to use glazier’s points in another, etc…
      • And link between them.
  • Topics vs. Documents
    • A document is one big chunk of content.
      • Difficult or impossible to subdivide and re-assemble in different forms.
    • A topic is one little chunk of content.
      • Many topics can be threaded together to create the document and other forms – flexibility.
  • Topics vs. Documents
    • Think about creating a necklace for mom in arts and crafts period in summer camp.
      • You can buy a finished necklace (a document) in the camp store.
      • Or you can string together 100 beads (topics) in order to create the necklace yourself.
    • The latter clearly is more flexible – you choose the beads and their sequence.
    • What Is Structured Authoring?
  • What Is Structured Authoring?
    • Authoring with structure… duh?
      • No… doesn’t mean DITA or structured Frame.
      • Just says content has structure.
    • What constitutes “structure”?
      • Standard, consistent sectional and syntactical/ stylistic rules.
      • What technical communicators have always done, albeit usually manually…
    • Three definitions.
  • Definition 1
    • Visually structured – text in Normal style, formatted using the formatting toolbar.
      • A silly example, but what many authors view as “structured.”
      • A hurdle on the way to structured authoring.
      • Content formatted this way can be manipulated a bit, using RoboHelp’s Word import parser.
      • Look at the image on the next slide…
  • Definition 1 – Example
    • Structured?
  • Definition 2
    • Programmatically structured using styles, perhaps a CSS.
      • Better than #1 because it provides structure.
        • Typically through the use of head styles.
      • But the structure is up to the author, with no programmatic enforcement or locking.
      • Look at the image on the next slide…
  • Definition 2 – Example
    • Structured?
  • Definition 3
    • Programmatically and visually structured using templates and a CSS – today’s focus.
      • Better than #2 because it makes it easier to add structure and corresponding styles.
        • Entries in each template field automatically get the style assigned to that field.
      • But the structure is still up to the author, with no programmatic enforcement or locking.
      • For that, you need definition 4.
  • Definition 4
    • Programmatically structured via a DTD or XSD, like DITA.
      • May be the best choice because it supports and enforces structure programmatically, but may not be appropriate for you.
  • Section 2: Rationales for Use…
    • Why?
    • Why Now?
    • Why Not?
    • Why?
  • Shifting Technology Demands
    • We may be needing multiple outputs for multiple audiences.
    • Generating them cost-effectively requires ability to select content for each audience and automate the processing.
    • But that content selection and automated processing requires content in selectable chunks with a controlled structure.
  • Major Benefits
    • In no particular order…
      • Flexible – Chunked content= finer processing.
      • Multi-developer capable – Chunked content supports many developers simultaneously.
      • Consistent – Aids in writing, processing auto-mation, maintenance, reduced editorial needs (if you even have an editor), readibility.
      • Fewer errors – Content is only written once.
  • Major Benefits
      • Ownership – One owner per chunk of content.
      • Technology-forward – Looks more up-to-date.
      • More CMS integratable – Self-explanatory.
      • Better future-proofed – May be able to re-use the content for output types that may not have existed when you began this effort.
      • And new outputs appear quickly…
  • Changing Outputs
    • Look at the acceleration…
      • 1946 – Hypertext postulated.
      • 1985 – Early PC-based hypertext systems.
      • 1991 – WinHelp 3.1 appears.
      • 1995 – WinHelp 4 appears.
      • 1996 – HTML Help announced.
      • 1996 – NetHelp announced.
      • 1997 – XML appears.
      • 1998 – eHelp releases WebHelp.
  • Changing Outputs
    • More…
      • 1998 – Netscape kills NetHelp.
      • 2001 – MS pre-announces Help 2.0 for 2002.
      • 2002 – eHelp introduces Flash Help.
      • 2002 – MS delays Help 2.0 by a year.
      • 2002 – IBM starts pushing DITA.
      • 2005 – XHTML begins replacing HTML.
      • RIM, Symbian, iPhone, Windows Mobile, others enter the picture over ~10 years.
  • Changing Outputs
    • Note several things:
      • Accelerating pace of change.
        • Less time to experiment now.
      • Spread of HTML/XML-based formats – e.g. shift toward open-source.
      • So why move to topic-based authoring and structured authoring?
  • One More Benefit
    • Topic-based authoring is a facet of formal structured authoring methodologies like DITA.
    • Even without DITA, topic-based authoring supports informal structured authoring via HATs and word-processors.
    • That flexibility helps support the company content strategy.
      • May equal greater job security.
  • Why Now ?
    • You’re at a transition point as you prepare to go online or switch online formats.
    • There’s a clear set of problems and topic-based and structured authoring appear to be the solution.
    • Topic-based and structured authoring are hot and trendy, like us…
  • Why Not Now?
    • Topic-based authoring has been way over-hyped.
      • Lack of a real-world analog makes it hard for authors to internalize.
      • Lack of flow between topics makes it hard for authors to stay focused as they write.
      • Outputs that need different writing styles, as in tech support and marketing, make re-use hard.
      • Editing many variations in each topic causes MEGO (my eyes glaze over).
  • Why Not Now?
    • Hard to manage.
      • A topic should be the smallest unit of content that answers a question.
      • If you re-use smaller topics to create multiple outputs, like combining field description topics to create larger dialog box topics, the number of permutations can become unmanageable.
      • Hard to communicate management details to the next generation of developers.
  • Section 3: Strategy and Tactics
    • Strategy – Philosophy and Goals
    • Tactics – Specific Planning Issues
    • Strategy – Philosophy and Goals
  • Philosophy
    • KISS!!!!
    • Plan before you begin in order to:
      • Minimize flailing and operational disruption during implementation.
      • Help internalize the processes in the company.
      • Minimize feature and expectation creep.
      • Avoid becoming a political football.
    • But avoid paralysis by analysis.
  • Philosophy
    • If you don’t plan and internalize:
      • Feature creep will lead to inflated expectations among writers and management.
        • Especially if there’s a political aspect to the creep.
      • Expectations creep will lead to disappointment, recriminations, possible failure.
      • Even if the effort succeeds, it will vanish once the current champions move on.
  • Points to Consider
    • Is there a company or group philosophy?
      • Take/don’t take risks.
      • Project a cutting edge face to the clients.
      • Other…
    • Does structured information fit in with:
      • That tone and philosophy?
      • Our staff’s skills and temperaments?
        • How young, and technically astute, is the staff?
  • Goals
    • What doc group goals are we pursuing?
    • What company goals are we pursuing?
      • Does the company know or care that the doc group is pursuing those goals – e.g. indicates doc’s credibility within the company.
  • Points to Consider
    • Why do you want to do this?
    • Tactics – Specific Planning Issues
  • The Planning Issues
    • From large-scale to small.
      • Environment.
      • Project management. Strategic
      • Standards.
      • Information design.
      • Sources of content.
      • Control mechanisms. Tactical
      • Writing.
      • Tools.
  • Environment Issues
    • Strategic Fit
    • Group Representation
    • Politics
    • Role of the Consultant
  • Strategic Fit
    • In the old days, the doc group just created hard-copy and didn’t have to know about strategic direction.
    • Today, as online documentation has to fit the apps and new technology (Twitter for user doc!?), we have to pay attention.
  • Define the Strategic Fit
    • Strategy and goals.
      • Learn the company’s strategic plan in general and with regard to “content,” NOT “doc.”
      • Help set that content direction.
      • Doing so means thinking ahead and extensibly.
        • Will today’s format choices work with or be easily converted to future formats?
        • New technologies, usage models, types of apps?
  • Points to Consider
    • What is your company’s direction?
      • In general?
      • With regard to “content”?
    • Can the doc group help?
    • Is the doc group getting in the way, such as fighting social media?
  • Group Representation
    • Who represents the doc group to the out-side world during this effort?
    • With what credibility?
      • Willingness to speak other groups’ language.
      • Effect of company culture when picking reps.
        • Young, petite, shy women may have problems.
        • So may lone reps and hostile writers.
        • Need a political sense.
      • Team reps must participate in all events.
  • Points to Consider
    • Who are your candidates to represent the doc group to the outside world?
  • Politics
    • Any effort will fail if it doesn’t consider company politics, such as:
      • Participants’ ego.
      • Lack of realism.
      • Posturing.
      • Ownership.
      • Competitors.
  • Participants’ Ego
    • Drifting into an effort in order to do cool things for:
      • Professional growth.
      • The acclaim of your peers.
    • Being unwilling to kill a bad effort for fear of losing a great professional opportunity.
  • Lack of Realism
    • Management’s wanting to shrink the doc group by having the engineers write the content.
      • Before you laugh, consider social media…
    • Management’s attempt to “automate” doc work via a CMS.
      • Rolling up a multi-step task like doc into one bullet point to make it look overly simple.
  • Posturing
    • Managers wanting to “take bold leaps,” even if a “leap” is impractical, unneeded, or even detrimental.
      • Risky since “bold leaps” come from politicians who’ll be gone when the project dies.
      • Most common on highly visible projects.
      • Build horizontal and vertical support and be prepared to justify all decisions.
  • Ownership
    • This effort will require someone to give up some power.
    • No one ever does this willingly.
      • Especially if the idea is coming from the doc group…
  • Competitors
    • “Content” is cool and pays well, so consultants are emerging as competitors.
    • We have to get attuned to the big picture of the company to compete with them.
    • If we don’t, we lose a great opportunity to increase our range of operations, visibility, and perceived value.
  • The Role of the Consultant
    • Typical roles:
      • Validator – Reviews the work so far to see if things are on the right track.
      • Emcee/shield/sacrificial lamb – Helps select between alternatives.
      • Legitimator – Gives the team an imprimateur.
      • Substitute voice – Tells management what you’ve been saying, but is taken seriously.
      • Designated techie – Serves as the team’s technical rep in planning meetings.
  • Suggestions Re Consultants
    • Decide what you want out of a consultant before engaging one.
    • Be wary of global projects, glib answers.
    • Remember that ultimate responsibility is yours; you know your needs better than any consultant.
    • “ Effective change agents don’t run around yelling about it.”
  • Points to Consider
    • What’s your political climate?
    • Might a consultant help?
      • What track record or reputation do consultants have in your company?
  • Project Management Issues
    • Keeping Up
    • Legacy Material
    • Metrics
    • Project Specs
  • Keeping Up
    • Technology and tools are advancing so fast that it’s hard to keep up.
      • Technology names are confusingly similar:
        • WebHelp vs. Web Help.
        • HTML Help vs. HTML help.
        • Single sourcing vs. multi-channel publishing.
    • Two issues:
      • What are these new technologies? Tools?
      • How and when may they affect my company?
  • Keeping Up
    • Your concerns:
      • You can’t be an expert in all areas, but at least know what they are.
      • Know what they are before starting a project or hiring someone for a project based on these technologies.
      • It’s risky to learn about the technologies during a project from the consultant hired to do it.
  • Points to Consider
    • Can we set up continuing education events – lunch-time seminars, designated techies, etc?
    • Will the group’s culture accept this?
  • Legacy Material
    • Before starting a TBA/SA effort, inventory your materials in and outside the doc group in order to identify:
      • What’s no longer needed.
      • What’s duplicated elsewhere.
      • What’s needed but can be left as is.
      • What should be TBA’d and SA’d.
  • Benefits of This Inventory
    • Discard unused material.
    • Establish cut-off dates for material.
    • Prioritize material to be structured.
    • Identify political priorities.
    • The result – a cleaned-up inventory, even if you decide not to adopt TBA and SA.
  • Prioritization Criteria
    • Prioritize the legacy materials based on:
      • $ ROI.
      • Non-$ ROI.
      • Impact of business processes.
      • Political ramifications:
        • Building a base of support for further work.
        • Political risk – e.g. who owns what material and who can hurt you.
  • Points to Consider
    • Do you know what material you have to work with?
  • Metrics
    • Start tracking development metrics now to:
      • Plan future project resource needs.
      • Determine whether you reached your goals.
      • “ Sell” management on buying new software.
    • What to track.
      • Time to complete a project, divided by the number of topics or pages, which equals $.
    • Start now but ignore metrics from the first few projects while you’re getting your legs
  • Financial Metrics
    • Financial metrics basically take two forms:
      • Hard-dollar – Financial = higher revenue or lower expenses.
      • Soft-dollar – Have financial effects, such as:
        • Faster outputs = reduced development costs.
        • Better documentation = fewer support calls.
          • Which can reduce head-count in tech support, causing political problems with the tech support manager.
  • Points to Consider
    • At what expense level will your company require financial metrics?
    • What type of cost-justification method is required?
    • What’s the threshhold of return needed for approval?
  • Project Specs
    • “There’s never enough time to do it right, but there’s always enough time to go back and fix it. We hope…”
    • (Anonymous)
    • Too often, we start or inherit projects that lack any plan, direction, or description.
    • We waste time and resources figuring out what to do or just working blindly.
    • Good specs can fix this.
  • What’s A Spec?
    • A formal written description of the design, technical, and structural elements of one project or a set of related projects.
    • Serves four purposes:
      • Officially describes the project.
      • Validates the spec developer’s understanding of the project and its environment.
      • Helps keep all team members consistent.
      • Provides a reference for the next developer.
  • Who Should “Own” the Spec?
    • Someone, or else it will gather dust.
    • Depends on your organizational structure.
      • Usually the spec’s developer, the person most familiar with it.
    • Consider making spec ownership part of a job description.
    • Make spec handoff a formal step when the owner changes jobs.
  • Some Attributes of A Good Spec
    • Short - 100-page specs are impressive but no one reads or maintains them.
    • Flexible - Exceptions always occur. Add a deviation procedure.
    • Organizationally supported - Any group affected by the spec should have a say.
    • Controlled - There’s an owner, and a clear hand-off procedure when the owner leaves.
  • More Attributes of A Good Spec
    • Technically oriented - A spec isn’t a style guide, though it can include a style guide.
      • Assume that your writers know grammar.
    • Technically supported - Anything that can be controlled by a template should be.
    • Market-oriented - Your goal should be to create effective material that supports the products, not to win STC awards.
  • What Goes Into A Spec?
    • In general:
      • Administration.
      • Project, configuration, audience descriptions.
      • Information structure.
      • Navigation.
      • Interface features.
      • Tool and miscellaneous technical specs.
      • Development and record-keeping procedures.
      • Miscellaneous.
  • Points to Consider
    • Are there specs?
    • If so, who wrote them? When? Where are they? Are they adhered to? Is there any penalty for not adhering to them?
  • Standards Issues
    • In General
    • Structure and Appearance
    • Coding
    • Other
  • In General
    • Standardize anything you can.
    • Make the standards “invisible” if possible, like Flare’s master stylesheet.
    • Publicize the standards, train people on their use, and made adherence mandatory.
    • Major points on which to set standards…
  • Structure and Appearance
    • Template-based structure – Discussed shortly.
    • Styles – Discussed shortly.
    • Special effects – Minimize or eliminate.
      • Overpower content, irritating, troublesome when moving between different formats.
      • But you may not win awards without them.
  • Coding
    • Develop in-house expertise on the formats, tools, and conversion procedures.
      • Budget for training and conferences.
    • “Stay between the lines.”
      • Use tools correctly and avoid “hacks”.
        • “Hacks” usually involves breaking syntax rules.
  • WinHelp Watermark Hack
    • This code: Produced this:
  • WinHelp Watermark Hack
    • Which was “fixed” by the HAT’s HTML conversion tools to this:
  • Coding
    • Develop a policy to avoid code-level work.
      • Slow.
      • Quirky.
      • Error-prone.
      • Technically demanding, which narrows your hiring and contracting pool.
    • Replace local formatting with styles or a CSS.
      • Use character styles for text enhancement.
  • Coding
    • Design for flexibility.
      • Use font sets for cross-platform output.
      • Look at using relative units like % or ems in place of absolute units like pixels or inches.
    • Validate your code.
      • Not necessary, but a good way to check the cleanliness of your authoring tool’s output.
        • See www.flfsoft.com/html/html_validators.html
      • Get into the habit of creating clean code.
  • Topic Length – Single-Screen
    • Pro:
      • Easy to use.
    • Cons:
      • Hard to create.
      • Hard to maintain.
      • Hard to enforce if material will be translated.
      • Impossible to enforce if window is resizable.
  • Topic Length – Multi-Screen
    • Pro:
      • Solves all the “single-window” cons.
    • Cons:
      • No writing discipline required of developers.
      • May need bookmarks/link anchors, increasing project complexity.
  • Other
    • Writing – Discussed shortly.
    • Tools – Discussed shortly.
    • Placeholders and conditionality.
    • Indexing.
    • Other?
  • Points to Consider
    • What standards are in effect in your company?
    • Are they known? Followed?
    • Who wrote them? Controls them?
  • Information Design Issues
    • Information Types
    • Information Output Issues
    • Legacy Content History
    • Information Conversion Direction
    • Information Type Structure
  • Information Types
    • Define your information types and outputs.
      • The types of information you create regularly – concepts, task description, reference, show-me, troubleshooting, etc.
      • The bases of your topic templates.
      • Templates will consist of general elements, like headings, bulleted lists, etc., plus tool-specific elements, like Flare togglers.
  • Current Types?
    • Before starting, ask:
      • Do we have information types now?
      • Does anyone know what they are?
      • Do content providers follow them?
        • If not, are they amenable?
        • Do they need training?
      • Any tool changes required by providers?
      • Any “practice” barriers to change?
    • Without asking, you can waste your effort.
  • Information Output Issues
    • Define your outputs.
      • To define the tool features to use for each one.
      • Also to determine if any template elements will not convert well or at all to different outputs.
        • Will expanding text online convert to hard-copy?
        • Use hyperlinks or cross-references to create links for output to be created as online and hard-copy?
  • Legacy Content History
    • Determine when it was created, if you can.
      • Knowing the trends at that time may explain why things are the way they are.
    • Determine the authoring tool and techno-logy history, if you can.
      • May explain problems going between tools or tool versions.
  • Information Conversion Direction
    • For the outputs you identified, what’s your conversion direction?
      • Hard-copy to online or vice versa.
      • Helps determine what conversion problems you can ignore or have to fix.
  • Information Type Structures
    • Based on your analysis, specify required and optional elements and their structure for each type you defined.
      • For example, a task type has or may have:
        • Heads and subheads
        • Text
        • Bulleted and numbered lists
        • Graphics
        • Related topics lists, etc…
  • Conversion Problems
    • Consider elements that may depend on the tool, output, or conversion direction.
      • Browse buttons in WinHelp.
      • Hard-copy glossary that has a different form in HTML Help vs. WebHelp created using Flare.
    • This will help you determine:
      • Whether to drop or retain such elements.
      • Cross-format conversion features, and tools.
  • Information Type Structures
    • You now have a standard structure for each information type.
      • Elements and their sequence, hierarchy, and restrictions.
      • This doesn’t yet define how the elements will actually look – the styles.
  • Information Type Structures
    • For example, you might define the “task” type with these elements and rules.
      • Always starts with a title in Heading 1 style.
      • Title followed by text in Normal style.
        • Can include bulleted or numbered lists, etc.
      • Then a “Syntax” sub-head in Heading 2 style.
        • Can include bulleted or numbered lists, etc.
      • Then text in Normal style.
      • And so on...
  • Information Type Structures
    • Each type’s design should also specify:
      • Mandatory and optional elements.
      • Mandatory element sequences.
      • Things not to do, such as local formatting or using tables to control element alignment.
  • Sources of Content Issues
    • Sources of Content
  • Sources of Content
    • Why it matters…
    • We’d like this raw material to be usable in our outputs with no cleanup.
    • This depends on the content source.
    • Three main sources:
      • Traditional – From the doc group.
      • User-generated – In wikis, tweets, etc.
      • User-generated – In traditional tools like Word.
  • Traditional
    • From the doc group.
      • So the authors’ focus is writing.
      • In theory , they can make sure the material:
        • Is written well.
        • Follows structural and stylistic standards, etc.
  • User-Generated #1
    • From wikis, blogs, tweets, etc.
      • So the SMEs’ focus is not writing.
      • And the SMEs are using mediums that:
        • Support writing rather than “good” writing.
        • May not follow standards, because the medium doesn’t enforce or even offer them.
      • So there may be lots of cleanup unless you can get SMEs to write well and use standards, if the medium offers them.
  • User-Generated #2
    • From Word, maybe FrameMaker.
      • So the SMEs’ focus is not writing.
      • And the SMEs have probably not been trained in Word, and are using it badly:
        • In general.
        • In ways that don’t convert well.
      • So there may be lots of cleanup unless you can get SMEs to use Word better.
  • Points to Consider
    • Are we using our tools correctly? Are the SMEs?
      • If not, what do we do about it?
    • Are we using standards? Are the SMEs?
      • If not, what do we do about it?
  • Control Mechanism Issues
    • In General
    • Templates
    • Styles and CSS
    • Other Mechanisms
  • In General
    • Programmatic enablers of content creation and maintenance.
    • Many control mechanisms available, with the most useful, IMO, being:
      • Topic templates – Based on information types
      • Styles and style sheets
        • CSS media types (Flare)
      • Table styles and style sheets
  • Topic Templates
    • Based on information types.
      • Define the structures for the information types.
      • Should only need to define a few templates for all or most of your content.
      • If some content doesn’t fit your templates, you need to modify that content or define another template.
      • What follows are instructions for creating topic templates in major versions of Word, Flare, or RoboHelp.
  • Attributes of Good Templates
    • Limited to your information types.
    • Simple to use, especially for non-techie authors.
    • Intuitive , requiring little or no training.
    • Self-documenting .
    • Sold as benefiting users, not the doc group.
  • A Sample “Task” Template
    • [delete and type the title]
      • [type the description]
    • Required Materials
    • [type the list of materials. Press Enter once to add an item, twice for normal text]
    • Steps
    • [type the steps. Press Enter once to add a step, Enter twice to return to normal text]
    • and so on…
  • Topic Templates – Word ‘03
    • To create:
      • Create as a new document and apply styles.
      • Save as <template_name>.dot in Templates folder.
        • Using Templates folder makes the template visible without making users drill down to sub-folders.
        • Templates in C:Documents and Settings<your_ name>Application DataMicrosoftTemplates <sub-folder_if_any>
  • Topic Templates – Word ‘03
    • To use:
      • Select File/New, select On My Computer under Templates in New Document pane, and select desired template.
      • This is what you need to tell the SMEs – KISS!
  • Using Topic Templates – Word ‘03
  • Topic Templates – RH 8
    • “Master pages” in RH 8, “templates” in previous versions.
    • To create:
      • Right-click Master Pages folder on Project Set-up tab and select New Master Page.
      • Name, create, apply CSS, save as <template_ name>.htt in top-level project folder.
  • Topic Templates – RH 8
    • To use:
      • Click New Topic icon, select the master page from the Master Page pulldown on New Topic dialog box’s General tab.
  • Use Topic Templates – RH 8
  • Topic Templates – Flare 5 and 6
    • To create:
      • Create as new topic and apply CSS.
      • Create My DocumentsMy Templates sub-folder.
      • Create Content sub-folder under My Templates.
      • Save topic (template) in Content sub-folder.
  • Topic Templates – Flare 5 and 6
    • To use:
      • Click New Topic icon, select My Templates in Template Folders list, select desired template.
  • Use Topic Templates – Flare 5 and 6
  • Style Sheet (CSS)
    • A file containing all (ideally) or most of the format settings for a project.
    • Once you apply the styles in a style sheet to text, you can change all instances of a style by changing its properties once in the style sheet rather than in each instance.
  • Style Sheets – Word ‘03
    • Word adds styles to the template, rather than saving them as a separate CSS file.
    • So you won’t add styles separately for a Word document.
    • If importing Word documents into online authoring tools, you do want styles in the Word template to match those in the CSS as much as possible to reduce post-import cleanup.
  • Style Sheets – RH 8
    • To create:
      • Open a topic in Design mode.
      • Click Topic Properties icon, select Appearance tab, click New button for Style Sheet, name and save the CSS.
      • Define styles and attributes in Styles dialog box.
  • Style Sheets – RH 8
    • To use:
      • Select topics to which to apply CSS, click Topic Properties icon, select Appearance tab, and select desired CSS.
  • Style Sheets – Flare 5 and 6
    • To create:
      • Select Project > Add Stylesheet, name and save new CSS, define attributes using Stylesheet Editor in Simplified (easy) or Advanced (full power) view.
  • Style Sheets – Flare 5 and 6
    • To use:
      • Select desired topics in File List pane, click Properties icon, select Topic Properties tab, select desired CSS, or...
      • Select Project > Project Properties, select Default tab, select CSS in Master Stylesheet field.
  • Style Sheet Mediums (Flare)
    • To create one CSS for multiple outputs and set style properties for each output within that one CSS.
    • Done by defining “mediums” in the CSS that specify each output’s properties.
    • Efficient, but interface can be confusing at first.
    • Based on W3C Media Types standard.
  • Style Sheet Mediums
    • To create:
      • Create the CSS.
      • Select medium from Stylesheet Editor Medium pulldown or create one by selecting Options pulldown > Add Medium, then selecting it from the Medium pulldown.
      • Define the properties that differ in the medium.
        • Those you don’t define use the default settings.
  • Style Sheet Mediums
    • To use:
      • Create and define the target for the output.
      • Select the CSS for the project in the Master Stylesheet field on the Target Editor’s Basic tab.
      • Select the medium for the project in the Medium field on the Target Editor’s Advanced tab.
  • Table Style Sheets
    • Apply here to Flare and RoboHelp.
    • RoboHelp uses predefined table templates.
      • You can add table styles using the table Styles Editor.
      • These styles get added to the project’s CSS.
    • Flare lets you create table-specific CSSs using the TableStyle Editor.
      • These are standard CSSs focused on tables.
  • Table Styles – RH 8
    • To create:
      • Select Format > Styles, click the Create New Style icon, and select Table Style.
      • Name the table style and define its settings in the table Styles dialog box.
        • You can select and define successive Apply Formatting To… options.
  • Table Style Sheets – RH 8
    • To use:
      • Click in table to format, select Table > Table Style, and select the desired style.
      • If an imported table contains local styles that override a table style, first select the Clean Table Inline Formatting option.
  • Table Style Sheets – Flare 5 and 6
    • To create:
      • Select Project > Add Table Style…, name and save the CSS, define attributes using TableStyle Editor.
        • Can define general attributes, plus specific settings for header, footer, and normal rows, plus columns.
  • Table Style Sheets – Flare 5 and 6
    • To use:
      • Click in table to format, select Table > Table Properties, and select the desired style from the Table Style list on the Basic tab.
      • If an imported table contains local styles that override a table style, first select Table > Table Style, and Reset Local Cell Formatting.
  • Writing Issues
    • In General
    • Keep it Short
    • Keep it Simple
    • Keep it Consistent
    • Online-Specific Points
  • In General
    • Writing is an art that’s becoming a science.
    • Traditional creativity can be detrimental.
      • Makes us vulnerable to new competitors that don’t embrace “creative writing”.
      • Balance “perfect vs. good enough…”
    • Suggestions – General and online oriented.
  • Keep It Short – Simplicity
    • Use simple words and sentences.
      • Say “use” instead of “utilize”.
      • Say “Engineering is responsible for ***” rather than “The responsibility for *** is that of the Engineering department.”
      • Minimize compound sentences, prepositional phrases, subordinate and dependent clauses.
        • Prepositional phrase - starts with a preposition (like at, by, with, from, in regard to) followed by its object, acts like an adjective or an adverb
  • Keep It Short – Tense
    • Write step instructions in the present tense.
      • Say “…, the Print dialog box displays.” instead of “…, the Print dialog box will display.”
  • Keep It Short – Person
    • Write for the second person singular.
      • Say “After you click the OK button…” instead of “After the user clicks the OK button…”
      • This avoids gender neutral phrasing, cutting wording and eliminating syntactical ugliness like he/she and “the user…, they”.
        • “After you click the OK button, the Print dialog box displays.” instead of “After the user clicks the OK button, he/she will see the Print dialog box.”
  • Keep It Short – Voice
    • Active voice should be used rather than passive voice. (  ) 9 words.
      • Vs. “Use active voice rather than passive.” 6 words, 33% shorter.
      • Passive isn’t evil; it puts the emphasis of action on the recipient rather than the doer, as in:
        • The ball was thrown by Sue. vs.
        • Sue threw the ball.
      • But passive can be wordy, pompous, and hide responsibility.
  • Keep It Short – Voice
    • Passive is wordier than active.
      • Passive: After the key has been pressed by the user… 9 words
      • Active: After the user presses the key… 6 words – a 33% reduction.
      • Better yet: After you press the key… 5 words – a 44% reduction.
  • Keep It Short – Voice
    • Passive – professional or pompous?
      • Often used to sound professional or emphasize the writing over the writer.
      • But it often just sounds pompous:
        • Passive: Your assistance with this matter is greatly appreciated… (8 words) vs.
        • Active: We appreciate your assistance with this matter. (7 words), or
        • Thank you for your assistance… (5 words), or
        • We appreciate your assistance… (4 words).
  • Keep It Short – Voice
    • Passive – hiding responsibility…
      • Often used to obscure the doer of an action:
        • Passive: Your request for funding was rejected. vs.
        • Active: We rejected your request for funding.
        • Passive: An error was made processing your order. vs.
        • Active: We made an error processing your order.
        • And from a lawyer in a radio interview – “Look! Mistakes were made by a person, okay!”
  • Keep It Simple – Tables
    • Use step-action tables, phase-action tables, etc., to shorten material, reduce verbiage, and add white space and scanability.
  • Keep It Simple - Labeling
    • Labeling
      • Use as few head levels as possible.
      • Use gerund or infinitive – be consistent.
        • Recommend gerund to cut the extra word “To”.
      • Keep headings short, substantive, consistent.
        • Avoid vague words like “Using…” or “To…”
      • Use subheads within topics to make material short and scannable.
  • Keep It Consistent – Wording
    • Keep wording consistent but consider how to handle regional or company variations – sub vs. hoagie vs. …
      • Use indexing with synonyms and look for user feedback.
      • Find or develop standard word and phrase lists to ensure consistent wording, lower translation costs if using translation memory systems.
      • Consider using snippets and variables for this.
  • Keep It Consistent – Parallelism
    • Use parallel writing structures.
    • Start each instruction with an active verb – Press, Click, Type, etc.
      • Make an exception if you have to tell someone where to look before performing an instruction by starting with a location clause followed by a comma – e.g., “On the Widgets dialog box, click…”
  • Online-Specific Points
    • Cut relative references (above, etc).
      • “Above” fails if the target is in another topic.
    • Don’t write “click here”.
      • Old-fashioned.
      • The spoken “here” is useless to a blind reader.
    • Don’t number figure captions if topics that contain figures may be reused in different sequences.
    • Make sure headings work out of context.
  • Points to Consider
    • Can we establish writing standards?
    • Do we know if we already have standards?
      • If so, why are we creating new ones?
  • Tool Issues
    • Your Tool Environment
    • Tool Standardization
    • Tool Selection Factors
  • Your Tool Environment
    • Does your current tool still make sense?
      • Did you buy FrameMaker for long documents?
      • Do you still need to create one 500 page docu-ment or do you need 500 one-page topics?
      • If so, does FrameMaker still make sense?
    • Stay with standard doc tools like Word and Frame? Get a topic-based tool like Blaze? A topic-based online tool like Flare, RoboHelp, etc?
  • Tool Standardization
    • Standardize your authoring tools, using the same version of each tool.
      • Goal is to minimize the time spent fixing code problems caused by different tools or versions.
      • Try to select mainstream, commercial tools to ensure(?) their survival.
        • Avoid niche or shareware tools or internal utilities.
  • Tool Selection Factors
    • Technical factors:
      • Support for multi-developer projects using a CMS or VCS model or just server based.
      • Code “cleanliness” – minimal junk code.
      • Adherence to open source syntax.
      • Minimal proprietary codes and files.
      • Support for format conversion.
        • For example, RoboHelp 8 can import DITA using the DITA Open Toolkit but offers no support for it.
  • Tool Selection Factors
    • Business factors:
      • The vendor’s financial strength.
      • The software’s initial and maintenance costs.
  • Tool Selection Factors
    • Miscellaneous factors:
      • Developer-friendliness.
      • Availability of developers.
      • Degree of market support.
      • Vendor reputation.
      • Vendor responsiveness for support.
      • Learning difficulty.
  • Section 4: Hands-On Practice
    • The exercises…
    • Thank you... Questions?
    • Hyper/Word Services
    • 978-657-5464
    • [email_address]
    • www.hyperword.com
  • Hyper/Word Services Offers…
    • Training • Consulting • Development
      • Flare • RoboHelp • RoboInfo
      • Mimic • Captivate
      • XML
      • Single sourcing • Structured authoring