1.
Topic-Based and Structured Authoring

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.
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.
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.
<ul><li>Introduction </li></ul>

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.
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.
<ul><li>What Is Topic-Based Authoring? </li></ul>

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.
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.
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.
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.
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.
<ul><li>What Is Structured Authoring? </li></ul>

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.
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.
Definition 1 – Example <ul><li>Structured? </li></ul>

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.
Definition 2 – Example <ul><li>Structured? </li></ul>

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.
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.
Section 2: Rationales for Use… <ul><li>Why? </li></ul><ul><li>Why Now? </li></ul><ul><li>Why Not? </li></ul>

23.
<ul><li>Why? </li></ul>

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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
Section 3: Strategy and Tactics <ul><li>Strategy – Philosophy and Goals </li></ul><ul><li>Tactics – Specific Planning Issues </li></ul>

35.
<ul><li>Strategy – Philosophy and Goals </li></ul>

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.
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.
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.
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.
Points to Consider <ul><li>Why do you want to do this? </li></ul>

41.
<ul><li>Tactics – Specific Planning Issues </li></ul>

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.
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.
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.
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.
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.
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.
Points to Consider <ul><li>Who are your candidates to represent the doc group to the outside world? </li></ul>

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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
Points to Consider <ul><li>Do you know what material you have to work with? </li></ul>

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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
WinHelp Watermark Hack <ul><li>This code: Produced this: </li></ul>

81.
WinHelp Watermark Hack <ul><li>Which was “fixed” by the HAT’s HTML conversion tools to this: </li></ul>

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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
Sources of Content Issues <ul><li>Sources of Content </li></ul>

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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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:ocuments and Settingslt;your_ name>pplication Dataicrosoftemplates<sub-folder_if_any> </li></ul></ul></ul>

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.
Using Topic Templates – Word ‘03

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.
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.
Use Topic Templates – RH 8

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 Documentsy 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.
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.
Use Topic Templates – Flare 5 and 6

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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
Tool Issues <ul><li>Your Tool Environment </li></ul><ul><li>Tool Standardization </li></ul><ul><li>Tool Selection Factors </li></ul>

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.
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.
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.
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.
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.
Section 4: Hands-On Practice

155.
<ul><li>The exercises… </li></ul>

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