Topic based and structured authoring - slides

Topic-Based and Structured Authoring

Who Am I? Neil Perlin - Hyper/Word Services. In tech. comm. since ‘79 at DEC. Creating hypertext since ’85, WinHelp since ’90, HTML since ‘91. Training and consulting on HATs since ’95, XML, mobile devices, single-sourcing, structured authoring since ‘98. STC’s lead W3C rep – ’02 – ‘05. Certified in Flare, RoboHelp, Captivate, Mimic, others now gone.

Contents 1 – Definitions 2 – Rationales for Use 3 – Strategy and Tactics 4 – Hands-On Practice

Section 1: Definitions Introduction What’s Topic-Based Authoring? What’s Structured Authoring?

Workshop Goals Understand topic-based and structured authoring concepts to: Decide whether they make sense for you. Understand their larger context. Implement them without turning your world totally upside-down.

Workshop Philosophy and Caution Not to immediately jump to a standard or tool. Instead, make decisions deliberately. Avoid the “there’s never enough time to do it right but there should be time to go back and fix it later” approach. Avoid paralysis by over-analysis. Anticipate a continuing, often messy effort.

What Is Topic-Based Authoring?

What Is Topic-Based Authoring? Authoring content in the form of topics rather than documents or books. Trendy because of single sourcing and DITA, but not new. Arose in 1991 with Doc-To-Help. Or even in 1965 with InfoMapping.

What’s a Topic? As focused and self-contained as possible a discussion about a single subject. Focused – Answers one question – “How do I…?”, “What is…?”, etc. Is this DITA? Can be , but doesn’t have to be . Self-contained – Contains all info needed to answer the question. Related info is in separate topics. Each topic links to the related but separate topics.

What’s a Topic? (cont’d) Example – Info to fix a broken window… Put steps in one topic… Information about glass-making in another… A list of standard pane sizes in another… How to use glazier’s points in another, etc… And link between them.

Topics vs. Documents A document is one big chunk of content. Difficult or impossible to subdivide and re-assemble in different forms. A topic is one little chunk of content. Many topics can be threaded together to create the document and other forms – flexibility.

Topics vs. Documents Think about creating a necklace for mom in arts and crafts period in summer camp. You can buy a finished necklace (a document) in the camp store. Or you can string together 100 beads (topics) in order to create the necklace yourself. The latter clearly is more flexible – you choose the beads and their sequence.

What Is Structured Authoring? Authoring with structure… duh? No… doesn’t mean DITA or structured Frame. Just says content has structure. What constitutes “structure”? Standard, consistent sectional and syntactical/ stylistic rules. What technical communicators have always done, albeit usually manually… Three definitions.

Definition 1 Visually structured – text in Normal style, formatted using the formatting toolbar. A silly example, but what many authors view as “structured.” A hurdle on the way to structured authoring. Content formatted this way can be manipulated a bit, using RoboHelp’s Word import parser. Look at the image on the next slide…

Definition 1 – Example Structured?

Definition 2 Programmatically structured using styles, perhaps a CSS. Better than #1 because it provides structure. Typically through the use of head styles. But the structure is up to the author, with no programmatic enforcement or locking. Look at the image on the next slide…

Definition 2 – Example Structured?

Definition 3 Programmatically and visually structured using templates and a CSS – today’s focus. Better than #2 because it makes it easier to add structure and corresponding styles. Entries in each template field automatically get the style assigned to that field. But the structure is still up to the author, with no programmatic enforcement or locking. For that, you need definition 4.

Definition 4 Programmatically structured via a DTD or XSD, like DITA. May be the best choice because it supports and enforces structure programmatically, but may not be appropriate for you.

Section 2: Rationales for Use… Why? Why Now? Why Not?

Shifting Technology Demands We may be needing multiple outputs for multiple audiences. Generating them cost-effectively requires ability to select content for each audience and automate the processing. But that content selection and automated processing requires content in selectable chunks with a controlled structure.

Major Benefits In no particular order… Flexible – Chunked content= finer processing. Multi-developer capable – Chunked content supports many developers simultaneously. Consistent – Aids in writing, processing auto-mation, maintenance, reduced editorial needs (if you even have an editor), readibility. Fewer errors – Content is only written once.

Major Benefits Ownership – One owner per chunk of content. Technology-forward – Looks more up-to-date. More CMS integratable – Self-explanatory. Better future-proofed – May be able to re-use the content for output types that may not have existed when you began this effort. And new outputs appear quickly…

Changing Outputs Look at the acceleration… 1946 – Hypertext postulated. 1985 – Early PC-based hypertext systems. 1991 – WinHelp 3.1 appears. 1995 – WinHelp 4 appears. 1996 – HTML Help announced. 1996 – NetHelp announced. 1997 – XML appears. 1998 – eHelp releases WebHelp.

Changing Outputs More… 1998 – Netscape kills NetHelp. 2001 – MS pre-announces Help 2.0 for 2002. 2002 – eHelp introduces Flash Help. 2002 – MS delays Help 2.0 by a year. 2002 – IBM starts pushing DITA. 2005 – XHTML begins replacing HTML. RIM, Symbian, iPhone, Windows Mobile, others enter the picture over ~10 years.

Changing Outputs Note several things: Accelerating pace of change. Less time to experiment now. Spread of HTML/XML-based formats – e.g. shift toward open-source. So why move to topic-based authoring and structured authoring?

One More Benefit Topic-based authoring is a facet of formal structured authoring methodologies like DITA. Even without DITA, topic-based authoring supports informal structured authoring via HATs and word-processors. That flexibility helps support the company content strategy. May equal greater job security.

Why Now ? You’re at a transition point as you prepare to go online or switch online formats. There’s a clear set of problems and topic-based and structured authoring appear to be the solution. Topic-based and structured authoring are hot and trendy, like us…

Why Not Now? Topic-based authoring has been way over-hyped. Lack of a real-world analog makes it hard for authors to internalize. Lack of flow between topics makes it hard for authors to stay focused as they write. Outputs that need different writing styles, as in tech support and marketing, make re-use hard. Editing many variations in each topic causes MEGO (my eyes glaze over).

Why Not Now? Hard to manage. A topic should be the smallest unit of content that answers a question. If you re-use smaller topics to create multiple outputs, like combining field description topics to create larger dialog box topics, the number of permutations can become unmanageable. Hard to communicate management details to the next generation of developers.

Section 3: Strategy and Tactics Strategy – Philosophy and Goals Tactics – Specific Planning Issues

Strategy – Philosophy and Goals

Philosophy KISS!!!! Plan before you begin in order to: Minimize flailing and operational disruption during implementation. Help internalize the processes in the company. Minimize feature and expectation creep. Avoid becoming a political football. But avoid paralysis by analysis.

Philosophy If you don’t plan and internalize: Feature creep will lead to inflated expectations among writers and management. Especially if there’s a political aspect to the creep. Expectations creep will lead to disappointment, recriminations, possible failure. Even if the effort succeeds, it will vanish once the current champions move on.

Points to Consider Is there a company or group philosophy? Take/don’t take risks. Project a cutting edge face to the clients. Other… Does structured information fit in with: That tone and philosophy? Our staff’s skills and temperaments? How young, and technically astute, is the staff?

Goals What doc group goals are we pursuing? What company goals are we pursuing? Does the company know or care that the doc group is pursuing those goals – e.g. indicates doc’s credibility within the company.

Points to Consider Why do you want to do this?

Tactics – Specific Planning Issues

The Planning Issues From large-scale to small. Environment. Project management. Strategic Standards. Information design. Sources of content. Control mechanisms. Tactical Writing. Tools.

Environment Issues Strategic Fit Group Representation Politics Role of the Consultant

Strategic Fit In the old days, the doc group just created hard-copy and didn’t have to know about strategic direction. Today, as online documentation has to fit the apps and new technology (Twitter for user doc!?), we have to pay attention.

Define the Strategic Fit Strategy and goals. Learn the company’s strategic plan in general and with regard to “content,” NOT “doc.” Help set that content direction. Doing so means thinking ahead and extensibly. Will today’s format choices work with or be easily converted to future formats? New technologies, usage models, types of apps?

Points to Consider What is your company’s direction? In general? With regard to “content”? Can the doc group help? Is the doc group getting in the way, such as fighting social media?

Group Representation Who represents the doc group to the out-side world during this effort? With what credibility? Willingness to speak other groups’ language. Effect of company culture when picking reps. Young, petite, shy women may have problems. So may lone reps and hostile writers. Need a political sense. Team reps must participate in all events.

Points to Consider Who are your candidates to represent the doc group to the outside world?

Politics Any effort will fail if it doesn’t consider company politics, such as: Participants’ ego. Lack of realism. Posturing. Ownership. Competitors.

Participants’ Ego Drifting into an effort in order to do cool things for: Professional growth. The acclaim of your peers. Being unwilling to kill a bad effort for fear of losing a great professional opportunity.

Lack of Realism Management’s wanting to shrink the doc group by having the engineers write the content. Before you laugh, consider social media… Management’s attempt to “automate” doc work via a CMS. Rolling up a multi-step task like doc into one bullet point to make it look overly simple.

Posturing Managers wanting to “take bold leaps,” even if a “leap” is impractical, unneeded, or even detrimental. Risky since “bold leaps” come from politicians who’ll be gone when the project dies. Most common on highly visible projects. Build horizontal and vertical support and be prepared to justify all decisions.

Ownership This effort will require someone to give up some power. No one ever does this willingly. Especially if the idea is coming from the doc group…

Competitors “Content” is cool and pays well, so consultants are emerging as competitors. We have to get attuned to the big picture of the company to compete with them. If we don’t, we lose a great opportunity to increase our range of operations, visibility, and perceived value.

The Role of the Consultant Typical roles: Validator – Reviews the work so far to see if things are on the right track. Emcee/shield/sacrificial lamb – Helps select between alternatives. Legitimator – Gives the team an imprimateur. Substitute voice – Tells management what you’ve been saying, but is taken seriously. Designated techie – Serves as the team’s technical rep in planning meetings.

Suggestions Re Consultants Decide what you want out of a consultant before engaging one. Be wary of global projects, glib answers. Remember that ultimate responsibility is yours; you know your needs better than any consultant. “ Effective change agents don’t run around yelling about it.”

Points to Consider What’s your political climate? Might a consultant help? What track record or reputation do consultants have in your company?

Project Management Issues Keeping Up Legacy Material Metrics Project Specs

Keeping Up Technology and tools are advancing so fast that it’s hard to keep up. Technology names are confusingly similar: WebHelp vs. Web Help. HTML Help vs. HTML help. Single sourcing vs. multi-channel publishing. Two issues: What are these new technologies? Tools? How and when may they affect my company?

Keeping Up Your concerns: You can’t be an expert in all areas, but at least know what they are. Know what they are before starting a project or hiring someone for a project based on these technologies. It’s risky to learn about the technologies during a project from the consultant hired to do it.

Points to Consider Can we set up continuing education events – lunch-time seminars, designated techies, etc? Will the group’s culture accept this?

Legacy Material Before starting a TBA/SA effort, inventory your materials in and outside the doc group in order to identify: What’s no longer needed. What’s duplicated elsewhere. What’s needed but can be left as is. What should be TBA’d and SA’d.

Benefits of This Inventory Discard unused material. Establish cut-off dates for material. Prioritize material to be structured. Identify political priorities. The result – a cleaned-up inventory, even if you decide not to adopt TBA and SA.

Prioritization Criteria Prioritize the legacy materials based on: $ ROI. Non-$ ROI. Impact of business processes. Political ramifications: Building a base of support for further work. Political risk – e.g. who owns what material and who can hurt you.

Points to Consider Do you know what material you have to work with?

Metrics Start tracking development metrics now to: Plan future project resource needs. Determine whether you reached your goals. “ Sell” management on buying new software. What to track. Time to complete a project, divided by the number of topics or pages, which equals $. Start now but ignore metrics from the first few projects while you’re getting your legs

Financial Metrics Financial metrics basically take two forms: Hard-dollar – Financial = higher revenue or lower expenses. Soft-dollar – Have financial effects, such as: Faster outputs = reduced development costs. Better documentation = fewer support calls. Which can reduce head-count in tech support, causing political problems with the tech support manager.

Points to Consider At what expense level will your company require financial metrics? What type of cost-justification method is required? What’s the threshhold of return needed for approval?

Project Specs “There’s never enough time to do it right, but there’s always enough time to go back and fix it. We hope…” (Anonymous) Too often, we start or inherit projects that lack any plan, direction, or description. We waste time and resources figuring out what to do or just working blindly. Good specs can fix this.

What’s A Spec? A formal written description of the design, technical, and structural elements of one project or a set of related projects. Serves four purposes: Officially describes the project. Validates the spec developer’s understanding of the project and its environment. Helps keep all team members consistent. Provides a reference for the next developer.

Who Should “Own” the Spec? Someone, or else it will gather dust. Depends on your organizational structure. Usually the spec’s developer, the person most familiar with it. Consider making spec ownership part of a job description. Make spec handoff a formal step when the owner changes jobs.

Some Attributes of A Good Spec Short - 100-page specs are impressive but no one reads or maintains them. Flexible - Exceptions always occur. Add a deviation procedure. Organizationally supported - Any group affected by the spec should have a say. Controlled - There’s an owner, and a clear hand-off procedure when the owner leaves.

More Attributes of A Good Spec Technically oriented - A spec isn’t a style guide, though it can include a style guide. Assume that your writers know grammar. Technically supported - Anything that can be controlled by a template should be. Market-oriented - Your goal should be to create effective material that supports the products, not to win STC awards.

What Goes Into A Spec? In general: Administration. Project, configuration, audience descriptions. Information structure. Navigation. Interface features. Tool and miscellaneous technical specs. Development and record-keeping procedures. Miscellaneous.

Points to Consider Are there specs? If so, who wrote them? When? Where are they? Are they adhered to? Is there any penalty for not adhering to them?

Standards Issues In General Structure and Appearance Coding Other

In General Standardize anything you can. Make the standards “invisible” if possible, like Flare’s master stylesheet. Publicize the standards, train people on their use, and made adherence mandatory. Major points on which to set standards…

Structure and Appearance Template-based structure – Discussed shortly. Styles – Discussed shortly. Special effects – Minimize or eliminate. Overpower content, irritating, troublesome when moving between different formats. But you may not win awards without them.

Coding Develop in-house expertise on the formats, tools, and conversion procedures. Budget for training and conferences. “Stay between the lines.” Use tools correctly and avoid “hacks”. “Hacks” usually involves breaking syntax rules.

WinHelp Watermark Hack This code: Produced this:

WinHelp Watermark Hack Which was “fixed” by the HAT’s HTML conversion tools to this:

Coding Develop a policy to avoid code-level work. Slow. Quirky. Error-prone. Technically demanding, which narrows your hiring and contracting pool. Replace local formatting with styles or a CSS. Use character styles for text enhancement.

Coding Design for flexibility. Use font sets for cross-platform output. Look at using relative units like % or ems in place of absolute units like pixels or inches. Validate your code. Not necessary, but a good way to check the cleanliness of your authoring tool’s output. See www.flfsoft.com/html/html_validators.html Get into the habit of creating clean code.

Topic Length – Single-Screen Pro: Easy to use. Cons: Hard to create. Hard to maintain. Hard to enforce if material will be translated. Impossible to enforce if window is resizable.

Topic Length – Multi-Screen Pro: Solves all the “single-window” cons. Cons: No writing discipline required of developers. May need bookmarks/link anchors, increasing project complexity.

Other Writing – Discussed shortly. Tools – Discussed shortly. Placeholders and conditionality. Indexing. Other?

Points to Consider What standards are in effect in your company? Are they known? Followed? Who wrote them? Controls them?

Information Design Issues Information Types Information Output Issues Legacy Content History Information Conversion Direction Information Type Structure

Information Types Define your information types and outputs. The types of information you create regularly – concepts, task description, reference, show-me, troubleshooting, etc. The bases of your topic templates. Templates will consist of general elements, like headings, bulleted lists, etc., plus tool-specific elements, like Flare togglers.

Current Types? Before starting, ask: Do we have information types now? Does anyone know what they are? Do content providers follow them? If not, are they amenable? Do they need training? Any tool changes required by providers? Any “practice” barriers to change? Without asking, you can waste your effort.

Information Output Issues Define your outputs. To define the tool features to use for each one. Also to determine if any template elements will not convert well or at all to different outputs. Will expanding text online convert to hard-copy? Use hyperlinks or cross-references to create links for output to be created as online and hard-copy?

Legacy Content History Determine when it was created, if you can. Knowing the trends at that time may explain why things are the way they are. Determine the authoring tool and techno-logy history, if you can. May explain problems going between tools or tool versions.

Information Conversion Direction For the outputs you identified, what’s your conversion direction? Hard-copy to online or vice versa. Helps determine what conversion problems you can ignore or have to fix.

Information Type Structures Based on your analysis, specify required and optional elements and their structure for each type you defined. For example, a task type has or may have: Heads and subheads Text Bulleted and numbered lists Graphics Related topics lists, etc…

Conversion Problems Consider elements that may depend on the tool, output, or conversion direction. Browse buttons in WinHelp. Hard-copy glossary that has a different form in HTML Help vs. WebHelp created using Flare. This will help you determine: Whether to drop or retain such elements. Cross-format conversion features, and tools.

Information Type Structures You now have a standard structure for each information type. Elements and their sequence, hierarchy, and restrictions. This doesn’t yet define how the elements will actually look – the styles.

Information Type Structures For example, you might define the “task” type with these elements and rules. Always starts with a title in Heading 1 style. Title followed by text in Normal style. Can include bulleted or numbered lists, etc. Then a “Syntax” sub-head in Heading 2 style. Can include bulleted or numbered lists, etc. Then text in Normal style. And so on...

Information Type Structures Each type’s design should also specify: Mandatory and optional elements. Mandatory element sequences. Things not to do, such as local formatting or using tables to control element alignment.

Sources of Content Issues Sources of Content

Sources of Content Why it matters… We’d like this raw material to be usable in our outputs with no cleanup. This depends on the content source. Three main sources: Traditional – From the doc group. User-generated – In wikis, tweets, etc. User-generated – In traditional tools like Word.

Traditional From the doc group. So the authors’ focus is writing. In theory , they can make sure the material: Is written well. Follows structural and stylistic standards, etc.

User-Generated #1 From wikis, blogs, tweets, etc. So the SMEs’ focus is not writing. And the SMEs are using mediums that: Support writing rather than “good” writing. May not follow standards, because the medium doesn’t enforce or even offer them. So there may be lots of cleanup unless you can get SMEs to write well and use standards, if the medium offers them.

User-Generated #2 From Word, maybe FrameMaker. So the SMEs’ focus is not writing. And the SMEs have probably not been trained in Word, and are using it badly: In general. In ways that don’t convert well. So there may be lots of cleanup unless you can get SMEs to use Word better.

Points to Consider Are we using our tools correctly? Are the SMEs? If not, what do we do about it? Are we using standards? Are the SMEs? If not, what do we do about it?

Control Mechanism Issues In General Templates Styles and CSS Other Mechanisms

In General Programmatic enablers of content creation and maintenance. Many control mechanisms available, with the most useful, IMO, being: Topic templates – Based on information types Styles and style sheets CSS media types (Flare) Table styles and style sheets

Topic Templates Based on information types. Define the structures for the information types. Should only need to define a few templates for all or most of your content. If some content doesn’t fit your templates, you need to modify that content or define another template. What follows are instructions for creating topic templates in major versions of Word, Flare, or RoboHelp.

Attributes of Good Templates Limited to your information types. Simple to use, especially for non-techie authors. Intuitive , requiring little or no training. Self-documenting . Sold as benefiting users, not the doc group.

A Sample “Task” Template [delete and type the title] [type the description] Required Materials [type the list of materials. Press Enter once to add an item, twice for normal text] Steps [type the steps. Press Enter once to add a step, Enter twice to return to normal text] and so on…

Topic Templates – Word ‘03 To create: Create as a new document and apply styles. Save as <template_name>.dot in Templates folder. Using Templates folder makes the template visible without making users drill down to sub-folders. Templates in C:\Documents and Settings\<your_ name>\Application Data\Microsoft\Templates\ <sub-folder_if_any>

Topic Templates – Word ‘03 To use: Select File/New, select On My Computer under Templates in New Document pane, and select desired template. This is what you need to tell the SMEs – KISS!

Using Topic Templates – Word ‘03

Topic Templates – RH 8 “Master pages” in RH 8, “templates” in previous versions. To create: Right-click Master Pages folder on Project Set-up tab and select New Master Page. Name, create, apply CSS, save as <template_ name>.htt in top-level project folder.

Topic Templates – RH 8 To use: Click New Topic icon, select the master page from the Master Page pulldown on New Topic dialog box’s General tab.

Topic Templates – Flare 5 and 6 To create: Create as new topic and apply CSS. Create My Documents\My Templates sub-folder. Create Content sub-folder under My Templates. Save topic (template) in Content sub-folder.

Topic Templates – Flare 5 and 6 To use: Click New Topic icon, select My Templates in Template Folders list, select desired template.

Use Topic Templates – Flare 5 and 6

Style Sheet (CSS) A file containing all (ideally) or most of the format settings for a project. Once you apply the styles in a style sheet to text, you can change all instances of a style by changing its properties once in the style sheet rather than in each instance.

Style Sheets – Word ‘03 Word adds styles to the template, rather than saving them as a separate CSS file. So you won’t add styles separately for a Word document. If importing Word documents into online authoring tools, you do want styles in the Word template to match those in the CSS as much as possible to reduce post-import cleanup.

Style Sheets – RH 8 To create: Open a topic in Design mode. Click Topic Properties icon, select Appearance tab, click New button for Style Sheet, name and save the CSS. Define styles and attributes in Styles dialog box.

Style Sheets – RH 8 To use: Select topics to which to apply CSS, click Topic Properties icon, select Appearance tab, and select desired CSS.

Style Sheets – Flare 5 and 6 To create: Select Project > Add Stylesheet, name and save new CSS, define attributes using Stylesheet Editor in Simplified (easy) or Advanced (full power) view.

Style Sheets – Flare 5 and 6 To use: Select desired topics in File List pane, click Properties icon, select Topic Properties tab, select desired CSS, or... Select Project > Project Properties, select Default tab, select CSS in Master Stylesheet field.

Style Sheet Mediums (Flare) To create one CSS for multiple outputs and set style properties for each output within that one CSS. Done by defining “mediums” in the CSS that specify each output’s properties. Efficient, but interface can be confusing at first. Based on W3C Media Types standard.

Style Sheet Mediums To create: Create the CSS. Select medium from Stylesheet Editor Medium pulldown or create one by selecting Options pulldown > Add Medium, then selecting it from the Medium pulldown. Define the properties that differ in the medium. Those you don’t define use the default settings.

Style Sheet Mediums To use: Create and define the target for the output. Select the CSS for the project in the Master Stylesheet field on the Target Editor’s Basic tab. Select the medium for the project in the Medium field on the Target Editor’s Advanced tab.

Table Style Sheets Apply here to Flare and RoboHelp. RoboHelp uses predefined table templates. You can add table styles using the table Styles Editor. These styles get added to the project’s CSS. Flare lets you create table-specific CSSs using the TableStyle Editor. These are standard CSSs focused on tables.

Table Styles – RH 8 To create: Select Format > Styles, click the Create New Style icon, and select Table Style. Name the table style and define its settings in the table Styles dialog box. You can select and define successive Apply Formatting To… options.

Table Style Sheets – RH 8 To use: Click in table to format, select Table > Table Style, and select the desired style. If an imported table contains local styles that override a table style, first select the Clean Table Inline Formatting option.

Table Style Sheets – Flare 5 and 6 To create: Select Project > Add Table Style…, name and save the CSS, define attributes using TableStyle Editor. Can define general attributes, plus specific settings for header, footer, and normal rows, plus columns.

Table Style Sheets – Flare 5 and 6 To use: Click in table to format, select Table > Table Properties, and select the desired style from the Table Style list on the Basic tab. If an imported table contains local styles that override a table style, first select Table > Table Style, and Reset Local Cell Formatting.

Writing Issues In General Keep it Short Keep it Simple Keep it Consistent Online-Specific Points

In General Writing is an art that’s becoming a science. Traditional creativity can be detrimental. Makes us vulnerable to new competitors that don’t embrace “creative writing”. Balance “perfect vs. good enough…” Suggestions – General and online oriented.

Keep It Short – Simplicity Use simple words and sentences. Say “use” instead of “utilize”. Say “Engineering is responsible for ***” rather than “The responsibility for *** is that of the Engineering department.” Minimize compound sentences, prepositional phrases, subordinate and dependent clauses. Prepositional phrase - starts with a preposition (like at, by, with, from, in regard to) followed by its object, acts like an adjective or an adverb

Keep It Short – Tense Write step instructions in the present tense. Say “…, the Print dialog box displays.” instead of “…, the Print dialog box will display.”

Keep It Short – Person Write for the second person singular. Say “After you click the OK button…” instead of “After the user clicks the OK button…” This avoids gender neutral phrasing, cutting wording and eliminating syntactical ugliness like he/she and “the user…, they”. “After you click the OK button, the Print dialog box displays.” instead of “After the user clicks the OK button, he/she will see the Print dialog box.”

Keep It Short – Voice Active voice should be used rather than passive voice. (  ) 9 words. Vs. “Use active voice rather than passive.” 6 words, 33% shorter. Passive isn’t evil; it puts the emphasis of action on the recipient rather than the doer, as in: The ball was thrown by Sue. vs. Sue threw the ball. But passive can be wordy, pompous, and hide responsibility.

Keep It Short – Voice Passive is wordier than active. Passive: After the key has been pressed by the user… 9 words Active: After the user presses the key… 6 words – a 33% reduction. Better yet: After you press the key… 5 words – a 44% reduction.

Keep It Short – Voice Passive – professional or pompous? Often used to sound professional or emphasize the writing over the writer. But it often just sounds pompous: Passive: Your assistance with this matter is greatly appreciated… (8 words) vs. Active: We appreciate your assistance with this matter. (7 words), or Thank you for your assistance… (5 words), or We appreciate your assistance… (4 words).

Keep It Short – Voice Passive – hiding responsibility… Often used to obscure the doer of an action: Passive: Your request for funding was rejected. vs. Active: We rejected your request for funding. Passive: An error was made processing your order. vs. Active: We made an error processing your order. And from a lawyer in a radio interview – “Look! Mistakes were made by a person, okay!”

Keep It Simple – Tables Use step-action tables, phase-action tables, etc., to shorten material, reduce verbiage, and add white space and scanability.

Keep It Simple - Labeling Labeling Use as few head levels as possible. Use gerund or infinitive – be consistent. Recommend gerund to cut the extra word “To”. Keep headings short, substantive, consistent. Avoid vague words like “Using…” or “To…” Use subheads within topics to make material short and scannable.

Keep It Consistent – Wording Keep wording consistent but consider how to handle regional or company variations – sub vs. hoagie vs. … Use indexing with synonyms and look for user feedback. Find or develop standard word and phrase lists to ensure consistent wording, lower translation costs if using translation memory systems. Consider using snippets and variables for this.

Keep It Consistent – Parallelism Use parallel writing structures. Start each instruction with an active verb – Press, Click, Type, etc. Make an exception if you have to tell someone where to look before performing an instruction by starting with a location clause followed by a comma – e.g., “On the Widgets dialog box, click…”

Online-Specific Points Cut relative references (above, etc). “Above” fails if the target is in another topic. Don’t write “click here”. Old-fashioned. The spoken “here” is useless to a blind reader. Don’t number figure captions if topics that contain figures may be reused in different sequences. Make sure headings work out of context.

Points to Consider Can we establish writing standards? Do we know if we already have standards? If so, why are we creating new ones?

Tool Issues Your Tool Environment Tool Standardization Tool Selection Factors

Your Tool Environment Does your current tool still make sense? Did you buy FrameMaker for long documents? Do you still need to create one 500 page docu-ment or do you need 500 one-page topics? If so, does FrameMaker still make sense? Stay with standard doc tools like Word and Frame? Get a topic-based tool like Blaze? A topic-based online tool like Flare, RoboHelp, etc?

Tool Standardization Standardize your authoring tools, using the same version of each tool. Goal is to minimize the time spent fixing code problems caused by different tools or versions. Try to select mainstream, commercial tools to ensure(?) their survival. Avoid niche or shareware tools or internal utilities.

Tool Selection Factors Technical factors: Support for multi-developer projects using a CMS or VCS model or just server based. Code “cleanliness” – minimal junk code. Adherence to open source syntax. Minimal proprietary codes and files. Support for format conversion. For example, RoboHelp 8 can import DITA using the DITA Open Toolkit but offers no support for it.

Tool Selection Factors Business factors: The vendor’s financial strength. The software’s initial and maintenance costs.

Tool Selection Factors Miscellaneous factors: Developer-friendliness. Availability of developers. Degree of market support. Vendor reputation. Vendor responsiveness for support. Learning difficulty.

Thank you... Questions? Hyper/Word Services 978-657-5464 [email_address] www.hyperword.com

Hyper/Word Services Offers… Training • Consulting • Development Flare • RoboHelp • RoboInfo Mimic • Captivate XML Single sourcing • Structured authoring

Topic based and structured authoring - slides

More Related Content

Viewers also liked (20)

Similar to Topic based and structured authoring - slides (20)

More from Neil Perlin (10)

Recently uploaded (20)

Topic based and structured authoring - slides

Editor's Notes