Topic-Based and Structured Authoring
Who Am I? <ul><li>Neil Perlin - Hyper/Word Services. </li></ul><ul><ul><li>In tech. comm. since ‘79 at DEC. </li></ul></ul...
Contents <ul><li>1 – Definitions </li></ul><ul><li>2 – Rationales for Use </li></ul><ul><li>3 – Strategy and Tactics </li>...
Section 1: Definitions <ul><li>Introduction </li></ul><ul><li>What’s Topic-Based Authoring? </li></ul><ul><li>What’s Struc...
<ul><li>Introduction </li></ul>
Workshop Goals <ul><li>Understand topic-based and structured authoring concepts to: </li></ul><ul><ul><li>Decide whether t...
Workshop Philosophy and Caution <ul><li>Not to immediately jump to a standard or tool. </li></ul><ul><li>Instead, make dec...
<ul><li>What Is Topic-Based Authoring? </li></ul>
What Is Topic-Based Authoring? <ul><li>Authoring content in the form of topics rather than documents or books. </li></ul><...
What’s a Topic? <ul><li>As focused and self-contained  as possible  a discussion about a single subject. </li></ul><ul><ul...
What’s a Topic? (cont’d) <ul><li>Example – Info to fix a broken window… </li></ul><ul><ul><li>Put steps in one topic… </li...
Topics vs. Documents <ul><li>A document is one big chunk of content. </li></ul><ul><ul><li>Difficult or impossible to subd...
Topics vs. Documents <ul><li>Think about creating a necklace for mom in arts and crafts period in summer camp. </li></ul><...
<ul><li>What Is Structured Authoring? </li></ul>
What Is Structured Authoring? <ul><li>Authoring with structure… duh? </li></ul><ul><ul><li>No… doesn’t mean DITA or struct...
Definition 1 <ul><li>Visually  structured – text in Normal style, formatted using the formatting toolbar. </li></ul><ul><u...
Definition 1 – Example <ul><li>Structured? </li></ul>
Definition 2 <ul><li>Programmatically  structured using styles, perhaps a CSS. </li></ul><ul><ul><li>Better than #1 becaus...
Definition 2 – Example <ul><li>Structured? </li></ul>
Definition 3 <ul><li>Programmatically   and visually  structured using templates and a CSS – today’s focus. </li></ul><ul>...
Definition 4 <ul><li>Programmatically  structured via a DTD or XSD, like DITA. </li></ul><ul><ul><li>May be the best choic...
Section 2: Rationales for Use… <ul><li>Why? </li></ul><ul><li>Why Now? </li></ul><ul><li>Why Not? </li></ul>
<ul><li>Why? </li></ul>
Shifting Technology Demands <ul><li>We may be needing multiple outputs for multiple audiences. </li></ul><ul><li>Generatin...
Major Benefits <ul><li>In no particular order… </li></ul><ul><ul><li>Flexible – Chunked content= finer processing. </li></...
Major Benefits <ul><ul><li>Ownership – One owner per chunk of content. </li></ul></ul><ul><ul><li>Technology-forward – Loo...
Changing Outputs <ul><li>Look at the acceleration… </li></ul><ul><ul><li>1946 – Hypertext postulated. </li></ul></ul><ul><...
Changing Outputs <ul><li>More… </li></ul><ul><ul><li>1998 – Netscape kills NetHelp. </li></ul></ul><ul><ul><li>2001 – MS p...
Changing Outputs <ul><li>Note several things: </li></ul><ul><ul><li>Accelerating pace of change. </li></ul></ul><ul><ul><u...
One More Benefit <ul><li>Topic-based authoring is a facet of formal structured authoring methodologies like DITA. </li></u...
Why  Now ? <ul><li>You’re at a transition point as you prepare to go online or switch online formats. </li></ul><ul><li>Th...
Why  Not  Now? <ul><li>Topic-based authoring has been way over-hyped. </li></ul><ul><ul><li>Lack of a real-world analog ma...
Why  Not  Now? <ul><li>Hard to manage. </li></ul><ul><ul><li>A topic should be the smallest unit of content that answers a...
Section 3: Strategy and Tactics <ul><li>Strategy – Philosophy and Goals </li></ul><ul><li>Tactics – Specific Planning Issu...
<ul><li>Strategy – Philosophy and Goals </li></ul>
Philosophy <ul><li>KISS!!!! </li></ul><ul><li>Plan before you begin in order to: </li></ul><ul><ul><li>Minimize flailing a...
Philosophy <ul><li>If you don’t plan and internalize: </li></ul><ul><ul><li>Feature creep will lead to inflated expectatio...
Points to Consider <ul><li>Is there a company or group philosophy? </li></ul><ul><ul><li>Take/don’t take risks. </li></ul>...
Goals <ul><li>What doc group goals are we pursuing? </li></ul><ul><li>What company goals are we pursuing? </li></ul><ul><u...
Points to Consider <ul><li>Why do you want to do this? </li></ul>
<ul><li>Tactics – Specific Planning Issues </li></ul>
The Planning Issues <ul><li>From large-scale to small. </li></ul><ul><ul><li>Environment.  </li></ul></ul><ul><ul><li>Proj...
Environment Issues <ul><li>Strategic Fit </li></ul><ul><li>Group Representation </li></ul><ul><li>Politics </li></ul><ul><...
Strategic Fit <ul><li>In the old days, the doc group just created hard-copy and didn’t have to know about strategic direct...
Define the Strategic Fit <ul><li>Strategy and goals. </li></ul><ul><ul><li>Learn the company’s strategic plan in general a...
Points to Consider <ul><li>What is your company’s direction? </li></ul><ul><ul><li>In general? </li></ul></ul><ul><ul><li>...
Group Representation <ul><li>Who represents the doc group to the out-side world during this effort? </li></ul><ul><li>With...
Points to Consider <ul><li>Who are your candidates to represent the doc group to the outside world? </li></ul>
Politics <ul><li>Any effort will fail if it doesn’t consider company politics, such as: </li></ul><ul><ul><li>Participants...
Participants’ Ego <ul><li>Drifting into an effort in order to do cool things for: </li></ul><ul><ul><li>Professional growt...
Lack of Realism <ul><li>Management’s wanting to shrink the doc group by having the engineers write the content. </li></ul>...
Posturing <ul><li>Managers wanting to “take bold leaps,” even if a “leap” is impractical, unneeded, or even detrimental. <...
Ownership <ul><li>This effort will require someone to give up some power. </li></ul><ul><li>No one ever does this willingl...
Competitors <ul><li>“Content” is cool and pays well, so consultants are emerging as competitors. </li></ul><ul><li>We have...
The Role of the Consultant <ul><li>Typical roles: </li></ul><ul><ul><li>Validator – Reviews the work so far to see if thin...
Suggestions Re Consultants <ul><li>Decide what you want out of a consultant before engaging one. </li></ul><ul><li>Be wary...
Points to Consider <ul><li>What’s your political climate? </li></ul><ul><li>Might a consultant help? </li></ul><ul><ul><li...
Project Management Issues <ul><li>Keeping Up </li></ul><ul><li>Legacy Material </li></ul><ul><li>Metrics </li></ul><ul><li...
Keeping Up <ul><li>Technology and tools are advancing so fast that it’s hard to keep up. </li></ul><ul><ul><li>Technology ...
Keeping Up <ul><li>Your concerns: </li></ul><ul><ul><li>You can’t be an expert in all areas, but at least know what they a...
Points to Consider <ul><li>Can we set up continuing education events – lunch-time seminars, designated techies, etc? </li>...
Legacy Material <ul><li>Before starting a TBA/SA effort, inventory your materials in and outside the doc group in order to...
Benefits of This Inventory <ul><li>Discard unused material. </li></ul><ul><li>Establish cut-off dates for material. </li><...
Prioritization Criteria <ul><li>Prioritize the legacy materials based on: </li></ul><ul><ul><li>$ ROI. </li></ul></ul><ul>...
Points to Consider <ul><li>Do you know what material you have to work with? </li></ul>
Metrics <ul><li>Start tracking development metrics now to: </li></ul><ul><ul><li>Plan future project resource needs. </li>...
Financial Metrics <ul><li>Financial metrics basically take two forms: </li></ul><ul><ul><li>Hard-dollar – Financial = high...
Points to Consider <ul><li>At what expense level will your company require financial metrics? </li></ul><ul><li>What type ...
Project Specs <ul><li>“There’s never enough time to do it right, but there’s always enough time to go back and fix it.  We...
What’s A Spec? <ul><li>A formal written description of the design, technical, and structural elements of one project or a ...
Who Should “Own” the Spec? <ul><li>Someone, or else it will gather dust. </li></ul><ul><li>Depends on your organizational ...
Some Attributes of A Good Spec <ul><li>Short - 100-page specs are impressive but no one reads or maintains them. </li></ul...
More Attributes of A Good Spec <ul><li>Technically oriented - A spec isn’t a style guide, though it can  include  a style ...
What Goes Into A Spec? <ul><li>In general: </li></ul><ul><ul><li>Administration. </li></ul></ul><ul><ul><li>Project, confi...
Points to Consider <ul><li>Are there specs? </li></ul><ul><li>If so, who wrote them?  When?  Where are they?  Are they adh...
Standards Issues <ul><li>In General </li></ul><ul><li>Structure and Appearance </li></ul><ul><li>Coding </li></ul><ul><li>...
In General <ul><li>Standardize anything you can. </li></ul><ul><li>Make the standards “invisible” if possible, like Flare’...
Structure and Appearance <ul><li>Template-based structure – Discussed shortly. </li></ul><ul><li>Styles – Discussed shortl...
Coding <ul><li>Develop in-house expertise on the formats, tools, and conversion procedures. </li></ul><ul><ul><li>Budget f...
WinHelp Watermark Hack  <ul><li>This code: Produced this: </li></ul>
WinHelp Watermark Hack  <ul><li>Which was “fixed” by the HAT’s HTML conversion tools to this: </li></ul>
Coding <ul><li>Develop a policy to avoid code-level work. </li></ul><ul><ul><li>Slow. </li></ul></ul><ul><ul><li>Quirky. <...
Coding <ul><li>Design for flexibility. </li></ul><ul><ul><li>Use font sets for cross-platform output. </li></ul></ul><ul><...
Topic Length – Single-Screen <ul><li>Pro: </li></ul><ul><ul><li>Easy to use. </li></ul></ul><ul><li>Cons: </li></ul><ul><u...
Topic Length – Multi-Screen <ul><li>Pro: </li></ul><ul><ul><li>Solves all the “single-window” cons. </li></ul></ul><ul><li...
Other <ul><li>Writing – Discussed shortly. </li></ul><ul><li>Tools – Discussed shortly. </li></ul><ul><li>Placeholders and...
Points to Consider <ul><li>What standards are in effect in your company? </li></ul><ul><li>Are they known?  Followed? </li...
Information Design Issues <ul><li>Information Types </li></ul><ul><li>Information Output Issues </li></ul><ul><li>Legacy C...
Information Types <ul><li>Define your information types and outputs. </li></ul><ul><ul><li>The types of information you cr...
Current Types? <ul><li>Before starting, ask: </li></ul><ul><ul><li>Do we have information types now? </li></ul></ul><ul><u...
Information Output Issues <ul><li>Define your outputs. </li></ul><ul><ul><li>To define the tool features to use for each o...
Legacy Content History <ul><li>Determine when it was created, if you can. </li></ul><ul><ul><li>Knowing the trends at that...
Information Conversion Direction <ul><li>For the outputs you identified, what’s your conversion direction? </li></ul><ul><...
Information Type Structures <ul><li>Based on your analysis, specify required and optional elements and their structure for...
Conversion Problems <ul><li>Consider elements that may depend on the tool, output, or conversion direction. </li></ul><ul>...
Information Type Structures <ul><li>You now have a standard structure for each information type. </li></ul><ul><ul><li>Ele...
Information Type Structures <ul><li>For example, you might define the “task” type with these elements and rules. </li></ul...
Information Type Structures <ul><li>Each type’s design should also specify: </li></ul><ul><ul><li>Mandatory and optional e...
Sources of Content Issues <ul><li>Sources of Content </li></ul>
Sources of Content <ul><li>Why it matters… </li></ul><ul><li>We’d like this raw material to be usable in our outputs with ...
Traditional <ul><li>From the doc group. </li></ul><ul><ul><li>So the authors’ focus is writing. </li></ul></ul><ul><ul><li...
User-Generated #1 <ul><li>From wikis, blogs, tweets, etc. </li></ul><ul><ul><li>So the SMEs’ focus is not writing. </li></...
User-Generated #2 <ul><li>From Word,  maybe  FrameMaker. </li></ul><ul><ul><li>So the SMEs’ focus is not writing. </li></u...
Points to Consider <ul><li>Are we using our tools correctly?  Are the SMEs? </li></ul><ul><ul><li>If not, what do we do ab...
Control Mechanism Issues <ul><li>In General </li></ul><ul><li>Templates </li></ul><ul><li>Styles and CSS </li></ul><ul><li...
In General <ul><li>Programmatic  enablers of content creation and maintenance. </li></ul><ul><li>Many control mechanisms a...
Topic Templates <ul><li>Based on information types. </li></ul><ul><ul><li>Define the structures for the information types....
Attributes of Good Templates <ul><li>Limited  to your information types. </li></ul><ul><li>Simple  to use, especially for ...
A Sample “Task” Template <ul><li>[delete and type the title] </li></ul><ul><ul><li>[type the description] </li></ul></ul><...
Topic Templates – Word ‘03 <ul><li>To create: </li></ul><ul><ul><li>Create as a new document and apply styles. </li></ul><...
Topic Templates – Word ‘03 <ul><li>To use: </li></ul><ul><ul><li>Select File/New, select On My Computer under Templates in...
Using Topic Templates – Word ‘03
Topic Templates – RH 8 <ul><li>“Master pages” in RH 8, “templates” in previous versions. </li></ul><ul><li>To create: </li...
Topic Templates – RH 8 <ul><li>To use: </li></ul><ul><ul><li>Click New Topic icon, select the master page from the Master ...
Use Topic Templates – RH 8
Topic Templates – Flare 5 and 6 <ul><li>To create: </li></ul><ul><ul><li>Create as new topic and apply CSS. </li></ul></ul...
Topic Templates – Flare 5 and 6 <ul><li>To use: </li></ul><ul><ul><li>Click New Topic icon, select My Templates in Templat...
Use Topic Templates – Flare 5 and 6
Style Sheet (CSS) <ul><li>A file containing all (ideally) or most of the format settings for a project. </li></ul><ul><li>...
Style Sheets – Word ‘03 <ul><li>Word adds styles to the template, rather than saving them as a separate CSS file. </li></u...
Style Sheets – RH 8 <ul><li>To create: </li></ul><ul><ul><li>Open a topic in Design mode. </li></ul></ul><ul><ul><li>Click...
Style Sheets – RH 8 <ul><li>To use: </li></ul><ul><ul><li>Select topics to which to apply CSS, click Topic Properties icon...
Style Sheets – Flare 5 and 6 <ul><li>To create: </li></ul><ul><ul><li>Select Project > Add Stylesheet, name and save new C...
Style Sheets – Flare 5 and 6 <ul><li>To use: </li></ul><ul><ul><li>Select desired topics in File List pane, click Properti...
Style Sheet Mediums (Flare) <ul><li>To create one CSS for multiple outputs and set style properties for each output within...
Style Sheet Mediums <ul><li>To create: </li></ul><ul><ul><li>Create the CSS. </li></ul></ul><ul><ul><li>Select medium from...
Style Sheet Mediums <ul><li>To use: </li></ul><ul><ul><li>Create and define the target for the output. </li></ul></ul><ul>...
Table Style Sheets <ul><li>Apply here to Flare and RoboHelp. </li></ul><ul><li>RoboHelp uses predefined table templates. <...
Table Styles – RH 8 <ul><li>To create: </li></ul><ul><ul><li>Select Format > Styles, click the Create New Style icon, and ...
Table Style Sheets – RH 8 <ul><li>To use: </li></ul><ul><ul><li>Click in table to format, select Table > Table Style, and ...
Table Style Sheets – Flare 5 and 6 <ul><li>To create: </li></ul><ul><ul><li>Select Project > Add Table Style…, name and sa...
Table Style Sheets – Flare 5 and 6 <ul><li>To use: </li></ul><ul><ul><li>Click in table to format, select Table > Table Pr...
Writing Issues <ul><li>In General </li></ul><ul><li>Keep it Short </li></ul><ul><li>Keep it Simple </li></ul><ul><li>Keep ...
In General <ul><li>Writing is an art that’s becoming a science. </li></ul><ul><li>Traditional creativity can be detrimenta...
Keep It Short – Simplicity <ul><li>Use simple words and sentences. </li></ul><ul><ul><li>Say “use” instead of “utilize”. <...
Keep It Short – Tense <ul><li>Write step instructions in the present tense.  </li></ul><ul><ul><li>Say “…, the Print dialo...
Keep It Short – Person <ul><li>Write for the second person singular.  </li></ul><ul><ul><li>Say “After you click the OK bu...
Keep It Short – Voice <ul><li>Active voice should be used rather than passive voice.  (  )  9 words. </li></ul><ul><ul><l...
Keep It Short – Voice <ul><li>Passive is wordier than active. </li></ul><ul><ul><li>Passive: After the key has been presse...
Keep It Short – Voice <ul><li>Passive – professional or pompous? </li></ul><ul><ul><li>Often used to sound professional or...
Keep It Short – Voice <ul><li>Passive – hiding responsibility… </li></ul><ul><ul><li>Often used to obscure the doer of an ...
Keep It Simple – Tables <ul><li>Use step-action tables, phase-action tables, etc., to shorten material, reduce verbiage, a...
Keep It Simple - Labeling <ul><li>Labeling </li></ul><ul><ul><li>Use as few head levels as possible. </li></ul></ul><ul><u...
Keep It Consistent – Wording <ul><li>Keep wording consistent but consider how to handle regional or company variations – s...
Keep It Consistent – Parallelism <ul><li>Use parallel writing structures. </li></ul><ul><li>Start each instruction with an...
Online-Specific Points <ul><li>Cut relative references (above, etc). </li></ul><ul><ul><li>“Above” fails if the target is ...
Points to Consider <ul><li>Can we establish writing standards? </li></ul><ul><li>Do we know if we already have standards? ...
Tool Issues <ul><li>Your Tool Environment </li></ul><ul><li>Tool Standardization </li></ul><ul><li>Tool Selection Factors ...
Your Tool Environment <ul><li>Does your current tool still make sense? </li></ul><ul><ul><li>Did you buy FrameMaker for lo...
Tool Standardization <ul><li>Standardize your authoring tools, using the same version of each tool. </li></ul><ul><ul><li>...
Tool Selection Factors <ul><li>Technical factors: </li></ul><ul><ul><li>Support for multi-developer projects using a CMS o...
Tool Selection Factors <ul><li>Business factors: </li></ul><ul><ul><li>The vendor’s financial strength. </li></ul></ul><ul...
Tool Selection Factors <ul><li>Miscellaneous factors: </li></ul><ul><ul><li>Developer-friendliness. </li></ul></ul><ul><ul...
Section 4: Hands-On Practice
<ul><li>The exercises… </li></ul>
<ul><li>Thank you... Questions? </li></ul><ul><li>Hyper/Word Services </li></ul><ul><li>978-657-5464 </li></ul><ul><li>[em...
Hyper/Word Services Offers… <ul><li>Training • Consulting • Development </li></ul><ul><ul><li>Flare  •  RoboHelp  •  RoboI...
Upcoming SlideShare
Loading in...5
×

Topic based and structured authoring - slides

4,950

Published on

Slides from topic-based/structured authoring workshop at Lavacon

Published in: Technology
0 Comments
1 Like
Statistics
Notes
  • Be the first to comment

No Downloads
Views
Total Views
4,950
On Slideshare
0
From Embeds
0
Number of Embeds
3
Actions
Shares
0
Downloads
81
Comments
0
Likes
1
Embeds 0
No embeds

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
  • Topic based and structured authoring - slides

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

      Clipping is a handy way to collect important slides you want to go back to later.

    ×