Your SlideShare is downloading. ×
Topic based and structured authoring - slides
Upcoming SlideShare
Loading in...5
×

Thanks for flagging this SlideShare!

Oops! An error has occurred.

×
Saving this for later? Get the SlideShare app to save on your phone or tablet. Read anywhere, anytime – even offline.
Text the download link to your phone
Standard text messaging rates apply

Topic based and structured authoring - slides

4,746
views

Published on

Slides from topic-based/structured authoring workshop at Lavacon

Slides from topic-based/structured authoring workshop at Lavacon

Published in: Technology

0 Comments
0 Likes
Statistics
Notes
  • Be the first to comment

  • Be the first to like this

No Downloads
Views
Total Views
4,746
On Slideshare
0
From Embeds
0
Number of Embeds
2
Actions
Shares
0
Downloads
77
Comments
0
Likes
0
Embeds 0
No embeds

Report content
Flagged as inappropriate Flag as inappropriate
Flag as inappropriate

Select your reason for flagging this presentation as inappropriate.

Cancel
No notes for slide
  • 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
  • Transcript

    • 1. Topic-Based and Structured Authoring
    • 2. 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.
    • 3. Contents
      • 1 – Definitions
      • 2 – Rationales for Use
      • 3 – Strategy and Tactics
      • 4 – Hands-On Practice
    • 4. Section 1: Definitions
      • Introduction
      • What’s Topic-Based Authoring?
      • What’s Structured Authoring?
    • 5.
      • Introduction
    • 6. 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.
    • 7. 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.
    • 8.
      • What Is Topic-Based Authoring?
    • 9. 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.
    • 10. 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.
    • 11. 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.
    • 12. 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.
    • 13. 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.
    • 14.
      • What Is Structured Authoring?
    • 15. 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.
    • 16. 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…
    • 17. Definition 1 – Example
      • Structured?
    • 18. 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…
    • 19. Definition 2 – Example
      • Structured?
    • 20. 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.
    • 21. 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.
    • 22. Section 2: Rationales for Use…
      • Why?
      • Why Now?
      • Why Not?
    • 23.
      • Why?
    • 24. 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.
    • 25. 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.
    • 26. 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…
    • 27. 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.
    • 28. 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.
    • 29. 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?
    • 30. 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.
    • 31. 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…
    • 32. 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).
    • 33. 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.
    • 34. Section 3: Strategy and Tactics
      • Strategy – Philosophy and Goals
      • Tactics – Specific Planning Issues
    • 35.
      • Strategy – Philosophy and Goals
    • 36. 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.
    • 37. 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.
    • 38. 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?
    • 39. 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.
    • 40. Points to Consider
      • Why do you want to do this?
    • 41.
      • Tactics – Specific Planning Issues
    • 42. The Planning Issues
      • From large-scale to small.
        • Environment.
        • Project management. Strategic
        • Standards.
        • Information design.
        • Sources of content.
        • Control mechanisms. Tactical
        • Writing.
        • Tools.
    • 43. Environment Issues
      • Strategic Fit
      • Group Representation
      • Politics
      • Role of the Consultant
    • 44. 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.
    • 45. 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?
    • 46. 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?
    • 47. 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.
    • 48. Points to Consider
      • Who are your candidates to represent the doc group to the outside world?
    • 49. Politics
      • Any effort will fail if it doesn’t consider company politics, such as:
        • Participants’ ego.
        • Lack of realism.
        • Posturing.
        • Ownership.
        • Competitors.
    • 50. 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.
    • 51. 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.
    • 52. 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.
    • 53. 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…
    • 54. 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.
    • 55. 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.
    • 56. 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.”
    • 57. Points to Consider
      • What’s your political climate?
      • Might a consultant help?
        • What track record or reputation do consultants have in your company?
    • 58. Project Management Issues
      • Keeping Up
      • Legacy Material
      • Metrics
      • Project Specs
    • 59. 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?
    • 60. 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.
    • 61. Points to Consider
      • Can we set up continuing education events – lunch-time seminars, designated techies, etc?
      • Will the group’s culture accept this?
    • 62. 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.
    • 63. 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.
    • 64. 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.
    • 65. Points to Consider
      • Do you know what material you have to work with?
    • 66. 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
    • 67. 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.
    • 68. 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?
    • 69. 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.
    • 70. 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.
    • 71. 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.
    • 72. 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.
    • 73. 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.
    • 74. 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.
    • 75. 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?
    • 76. Standards Issues
      • In General
      • Structure and Appearance
      • Coding
      • Other
    • 77. 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…
    • 78. 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.
    • 79. 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.
    • 80. WinHelp Watermark Hack
      • This code: Produced this:
    • 81. WinHelp Watermark Hack
      • Which was “fixed” by the HAT’s HTML conversion tools to this:
    • 82. 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.
    • 83. 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.
    • 84. 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.
    • 85. 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.
    • 86. Other
      • Writing – Discussed shortly.
      • Tools – Discussed shortly.
      • Placeholders and conditionality.
      • Indexing.
      • Other?
    • 87. Points to Consider
      • What standards are in effect in your company?
      • Are they known? Followed?
      • Who wrote them? Controls them?
    • 88. Information Design Issues
      • Information Types
      • Information Output Issues
      • Legacy Content History
      • Information Conversion Direction
      • Information Type Structure
    • 89. 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.
    • 90. 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.
    • 91. 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?
    • 92. 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.
    • 93. 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.
    • 94. 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…
    • 95. 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.
    • 96. 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.
    • 97. 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...
    • 98. 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.
    • 99. Sources of Content Issues
      • Sources of Content
    • 100. 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.
    • 101. 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.
    • 102. 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.
    • 103. 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.
    • 104. 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?
    • 105. Control Mechanism Issues
      • In General
      • Templates
      • Styles and CSS
      • Other Mechanisms
    • 106. 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
    • 107. 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.
    • 108. 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.
    • 109. 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…
    • 110. 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>
    • 111. 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!
    • 112. Using Topic Templates – Word ‘03
    • 113. 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.
    • 114. 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.
    • 115. Use Topic Templates – RH 8
    • 116. 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.
    • 117. Topic Templates – Flare 5 and 6
      • To use:
        • Click New Topic icon, select My Templates in Template Folders list, select desired template.
    • 118. Use Topic Templates – Flare 5 and 6
    • 119. 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.
    • 120. 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.
    • 121. 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.
    • 122. Style Sheets – RH 8
      • To use:
        • Select topics to which to apply CSS, click Topic Properties icon, select Appearance tab, and select desired CSS.
    • 123. 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.
    • 124. 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.
    • 125. 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.
    • 126. 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.
    • 127. 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.
    • 128. 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.
    • 129. 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.
    • 130. 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.
    • 131. 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.
    • 132. 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.
    • 133. Writing Issues
      • In General
      • Keep it Short
      • Keep it Simple
      • Keep it Consistent
      • Online-Specific Points
    • 134. 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.
    • 135. 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
    • 136. 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.”
    • 137. 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.”
    • 138. 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.
    • 139. 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.
    • 140. 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).
    • 141. 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!”
    • 142. Keep It Simple – Tables
      • Use step-action tables, phase-action tables, etc., to shorten material, reduce verbiage, and add white space and scanability.
    • 143. 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.
    • 144. 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.
    • 145. 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…”
    • 146. 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.
    • 147. Points to Consider
      • Can we establish writing standards?
      • Do we know if we already have standards?
        • If so, why are we creating new ones?
    • 148. Tool Issues
      • Your Tool Environment
      • Tool Standardization
      • Tool Selection Factors
    • 149. 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?
    • 150. 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.
    • 151. 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.
    • 152. Tool Selection Factors
      • Business factors:
        • The vendor’s financial strength.
        • The software’s initial and maintenance costs.
    • 153. Tool Selection Factors
      • Miscellaneous factors:
        • Developer-friendliness.
        • Availability of developers.
        • Degree of market support.
        • Vendor reputation.
        • Vendor responsiveness for support.
        • Learning difficulty.
    • 154. Section 4: Hands-On Practice
    • 155.
      • The exercises…
    • 156.
      • Thank you... Questions?
      • Hyper/Word Services
      • 978-657-5464
      • [email_address]
      • www.hyperword.com
    • 157. Hyper/Word Services Offers…
      • Training • Consulting • Development
        • Flare • RoboHelp • RoboInfo
        • Mimic • Captivate
        • XML
        • Single sourcing • Structured authoring