Skip to main content
UploadLanguage (EN)Support
BusinessMobileSocial MediaMarketingTechnologyArt & PhotosCareerDesignEducationPresentations & Public SpeakingGovernment & NonprofitHealthcareInternetLawLeadership & ManagementAutomotiveEngineeringSoftwareRecruiting & HRRetailSalesServicesScienceSmall Business & EntrepreneurshipFoodEnvironmentEconomy & FinanceData & AnalyticsInvestor RelationsSportsSpiritualNews & PoliticsTravelSelf ImprovementReal EstateEntertainment & HumorHealth & MedicineDevices & HardwareLifestyle
Neil Perlin, profile picture
Uploaded byNeil Perlin
PPT, PDF5,397 views

Topic based and structured authoring - slides

The document discusses topic-based and structured authoring approaches. It begins with introductions from the presenter and an overview of the contents. Section 1 defines topic-based authoring as authoring content in topics rather than documents, with each topic answering a single question. Structured authoring is defined as authoring with consistent sectional and stylistic rules. Section 2 discusses rationales for using these approaches, such as flexible reuse of content and consistency. Section 3 covers strategy, such as defining goals, and tactics, including project management, standards, and tools.

Technology◦
Downloaded 205 times
Topic-Based and Structured Authoring
Who Am I? Neil Perlin - Hyper/Word Services. In tech. comm. since ‘79 at DEC. Creating hypertext since ’85, WinHelp since ’90, HTML since ‘91. Training and consulting on HATs since ’95, XML, mobile devices, single-sourcing, structured authoring since ‘98. STC’s lead W3C rep – ’02 – ‘05. Certified in Flare, RoboHelp, Captivate, Mimic, others now gone.
Contents 1 – Definitions 2 – Rationales for Use 3 – Strategy and Tactics 4 – Hands-On Practice
Section 1: Definitions Introduction What’s Topic-Based Authoring? What’s Structured Authoring?
Introduction
Workshop Goals Understand topic-based and structured authoring concepts to: Decide whether they make sense for you. Understand their larger context. Implement them without turning your world totally upside-down.
Workshop Philosophy and Caution Not to immediately jump to a standard or tool. Instead, make decisions deliberately. Avoid the “there’s never enough time to do it right but there should be time to go back and fix it later” approach. Avoid paralysis by over-analysis. Anticipate a continuing, often messy effort.
What Is Topic-Based Authoring?
What Is Topic-Based Authoring? Authoring content in the form of topics rather than documents or books. Trendy because of single sourcing and DITA, but not new. Arose in 1991 with Doc-To-Help. Or even in 1965 with InfoMapping.
What’s a Topic? As focused and self-contained as possible a discussion about a single subject. Focused – Answers one question – “How do I…?”, “What is…?”, etc. Is this DITA? Can be , but doesn’t have to be . Self-contained – Contains all info needed to answer the question. Related info is in separate topics. Each topic links to the related but separate topics.
What’s a Topic? (cont’d) Example – Info to fix a broken window… Put steps in one topic… Information about glass-making in another… A list of standard pane sizes in another… How to use glazier’s points in another, etc… And link between them.
Topics vs. Documents A document is one big chunk of content. Difficult or impossible to subdivide and re-assemble in different forms. A topic is one little chunk of content. Many topics can be threaded together to create the document and other forms – flexibility.
Topics vs. Documents Think about creating a necklace for mom in arts and crafts period in summer camp. You can buy a finished necklace (a document) in the camp store. Or you can string together 100 beads (topics) in order to create the necklace yourself. The latter clearly is more flexible – you choose the beads and their sequence.
What Is Structured Authoring?
What Is Structured Authoring? Authoring with structure… duh? No… doesn’t mean DITA or structured Frame. Just says content has structure. What constitutes “structure”? Standard, consistent sectional and syntactical/ stylistic rules. What technical communicators have always done, albeit usually manually… Three definitions.
Definition 1 Visually structured – text in Normal style, formatted using the formatting toolbar. A silly example, but what many authors view as “structured.” A hurdle on the way to structured authoring. Content formatted this way can be manipulated a bit, using RoboHelp’s Word import parser. Look at the image on the next slide…
Definition 1 – Example Structured?
Definition 2 Programmatically structured using styles, perhaps a CSS. Better than #1 because it provides structure. Typically through the use of head styles. But the structure is up to the author, with no programmatic enforcement or locking. Look at the image on the next slide…
Definition 2 – Example Structured?
Definition 3 Programmatically and visually structured using templates and a CSS – today’s focus. Better than #2 because it makes it easier to add structure and corresponding styles. Entries in each template field automatically get the style assigned to that field. But the structure is still up to the author, with no programmatic enforcement or locking. For that, you need definition 4.
Definition 4 Programmatically structured via a DTD or XSD, like DITA. May be the best choice because it supports and enforces structure programmatically, but may not be appropriate for you.
Section 2: Rationales for Use… Why? Why Now? Why Not?
Why?
Shifting Technology Demands We may be needing multiple outputs for multiple audiences. Generating them cost-effectively requires ability to select content for each audience and automate the processing. But that content selection and automated processing requires content in selectable chunks with a controlled structure.
Major Benefits In no particular order… Flexible – Chunked content= finer processing. Multi-developer capable – Chunked content supports many developers simultaneously. Consistent – Aids in writing, processing auto-mation, maintenance, reduced editorial needs (if you even have an editor), readibility. Fewer errors – Content is only written once.
Major Benefits Ownership – One owner per chunk of content. Technology-forward – Looks more up-to-date. More CMS integratable – Self-explanatory. Better future-proofed – May be able to re-use the content for output types that may not have existed when you began this effort. And new outputs appear quickly…
Changing Outputs Look at the acceleration… 1946 – Hypertext postulated. 1985 – Early PC-based hypertext systems. 1991 – WinHelp 3.1 appears. 1995 – WinHelp 4 appears. 1996 – HTML Help announced. 1996 – NetHelp announced. 1997 – XML appears. 1998 – eHelp releases WebHelp.
Changing Outputs More… 1998 – Netscape kills NetHelp. 2001 – MS pre-announces Help 2.0 for 2002. 2002 – eHelp introduces Flash Help. 2002 – MS delays Help 2.0 by a year. 2002 – IBM starts pushing DITA. 2005 – XHTML begins replacing HTML. RIM, Symbian, iPhone, Windows Mobile, others enter the picture over ~10 years.
Changing Outputs Note several things: Accelerating pace of change. Less time to experiment now. Spread of HTML/XML-based formats – e.g. shift toward open-source. So why move to topic-based authoring and structured authoring?
One More Benefit Topic-based authoring is a facet of formal structured authoring methodologies like DITA. Even without DITA, topic-based authoring supports informal structured authoring via HATs and word-processors. That flexibility helps support the company content strategy. May equal greater job security.
Why Now ? You’re at a transition point as you prepare to go online or switch online formats. There’s a clear set of problems and topic-based and structured authoring appear to be the solution. Topic-based and structured authoring are hot and trendy, like us…
Why Not Now? Topic-based authoring has been way over-hyped. Lack of a real-world analog makes it hard for authors to internalize. Lack of flow between topics makes it hard for authors to stay focused as they write. Outputs that need different writing styles, as in tech support and marketing, make re-use hard. Editing many variations in each topic causes MEGO (my eyes glaze over).
Why Not Now? Hard to manage. A topic should be the smallest unit of content that answers a question. If you re-use smaller topics to create multiple outputs, like combining field description topics to create larger dialog box topics, the number of permutations can become unmanageable. Hard to communicate management details to the next generation of developers.
Section 3: Strategy and Tactics Strategy – Philosophy and Goals Tactics – Specific Planning Issues
Strategy – Philosophy and Goals
Philosophy KISS!!!! Plan before you begin in order to: Minimize flailing and operational disruption during implementation. Help internalize the processes in the company. Minimize feature and expectation creep. Avoid becoming a political football. But avoid paralysis by analysis.
Philosophy If you don’t plan and internalize: Feature creep will lead to inflated expectations among writers and management. Especially if there’s a political aspect to the creep. Expectations creep will lead to disappointment, recriminations, possible failure. Even if the effort succeeds, it will vanish once the current champions move on.
Points to Consider Is there a company or group philosophy? Take/don’t take risks. Project a cutting edge face to the clients. Other… Does structured information fit in with: That tone and philosophy? Our staff’s skills and temperaments? How young, and technically astute, is the staff?
Goals What doc group goals are we pursuing? What company goals are we pursuing? Does the company know or care that the doc group is pursuing those goals – e.g. indicates doc’s credibility within the company.
Points to Consider Why do you want to do this?
Tactics – Specific Planning Issues
The Planning Issues From large-scale to small. Environment. Project management. Strategic Standards. Information design. Sources of content. Control mechanisms. Tactical Writing. Tools.
Environment Issues Strategic Fit Group Representation Politics Role of the Consultant
Strategic Fit In the old days, the doc group just created hard-copy and didn’t have to know about strategic direction. Today, as online documentation has to fit the apps and new technology (Twitter for user doc!?), we have to pay attention.
Define the Strategic Fit Strategy and goals. Learn the company’s strategic plan in general and with regard to “content,” NOT “doc.” Help set that content direction. Doing so means thinking ahead and extensibly. Will today’s format choices work with or be easily converted to future formats? New technologies, usage models, types of apps?
Points to Consider What is your company’s direction? In general? With regard to “content”? Can the doc group help? Is the doc group getting in the way, such as fighting social media?
Group Representation Who represents the doc group to the out-side world during this effort? With what credibility? Willingness to speak other groups’ language. Effect of company culture when picking reps. Young, petite, shy women may have problems. So may lone reps and hostile writers. Need a political sense. Team reps must participate in all events.
Points to Consider Who are your candidates to represent the doc group to the outside world?
Politics Any effort will fail if it doesn’t consider company politics, such as: Participants’ ego. Lack of realism. Posturing. Ownership. Competitors.
Participants’ Ego Drifting into an effort in order to do cool things for: Professional growth. The acclaim of your peers. Being unwilling to kill a bad effort for fear of losing a great professional opportunity.
Lack of Realism Management’s wanting to shrink the doc group by having the engineers write the content. Before you laugh, consider social media… Management’s attempt to “automate” doc work via a CMS. Rolling up a multi-step task like doc into one bullet point to make it look overly simple.
Posturing Managers wanting to “take bold leaps,” even if a “leap” is impractical, unneeded, or even detrimental. Risky since “bold leaps” come from politicians who’ll be gone when the project dies. Most common on highly visible projects. Build horizontal and vertical support and be prepared to justify all decisions.
Ownership This effort will require someone to give up some power. No one ever does this willingly. Especially if the idea is coming from the doc group…
Competitors “Content” is cool and pays well, so consultants are emerging as competitors. We have to get attuned to the big picture of the company to compete with them. If we don’t, we lose a great opportunity to increase our range of operations, visibility, and perceived value.
The Role of the Consultant Typical roles: Validator – Reviews the work so far to see if things are on the right track. Emcee/shield/sacrificial lamb – Helps select between alternatives. Legitimator – Gives the team an imprimateur. Substitute voice – Tells management what you’ve been saying, but is taken seriously. Designated techie – Serves as the team’s technical rep in planning meetings.
Suggestions Re Consultants Decide what you want out of a consultant before engaging one. Be wary of global projects, glib answers. Remember that ultimate responsibility is yours; you know your needs better than any consultant. “ Effective change agents don’t run around yelling about it.”
Points to Consider What’s your political climate? Might a consultant help? What track record or reputation do consultants have in your company?
Project Management Issues Keeping Up Legacy Material Metrics Project Specs
Keeping Up Technology and tools are advancing so fast that it’s hard to keep up. Technology names are confusingly similar: WebHelp vs. Web Help. HTML Help vs. HTML help. Single sourcing vs. multi-channel publishing. Two issues: What are these new technologies? Tools? How and when may they affect my company?
Keeping Up Your concerns: You can’t be an expert in all areas, but at least know what they are. Know what they are before starting a project or hiring someone for a project based on these technologies. It’s risky to learn about the technologies during a project from the consultant hired to do it.
Points to Consider Can we set up continuing education events – lunch-time seminars, designated techies, etc? Will the group’s culture accept this?
Legacy Material Before starting a TBA/SA effort, inventory your materials in and outside the doc group in order to identify: What’s no longer needed. What’s duplicated elsewhere. What’s needed but can be left as is. What should be TBA’d and SA’d.
Benefits of This Inventory Discard unused material. Establish cut-off dates for material. Prioritize material to be structured. Identify political priorities. The result – a cleaned-up inventory, even if you decide not to adopt TBA and SA.
Prioritization Criteria Prioritize the legacy materials based on: $ ROI. Non-$ ROI. Impact of business processes. Political ramifications: Building a base of support for further work. Political risk – e.g. who owns what material and who can hurt you.
Points to Consider Do you know what material you have to work with?
Metrics Start tracking development metrics now to: Plan future project resource needs. Determine whether you reached your goals. “ Sell” management on buying new software. What to track. Time to complete a project, divided by the number of topics or pages, which equals $. Start now but ignore metrics from the first few projects while you’re getting your legs
Financial Metrics Financial metrics basically take two forms: Hard-dollar – Financial = higher revenue or lower expenses. Soft-dollar – Have financial effects, such as: Faster outputs = reduced development costs. Better documentation = fewer support calls. Which can reduce head-count in tech support, causing political problems with the tech support manager.
Points to Consider At what expense level will your company require financial metrics? What type of cost-justification method is required? What’s the threshhold of return needed for approval?
Project Specs “There’s never enough time to do it right, but there’s always enough time to go back and fix it. We hope…” (Anonymous) Too often, we start or inherit projects that lack any plan, direction, or description. We waste time and resources figuring out what to do or just working blindly. Good specs can fix this.
What’s A Spec? A formal written description of the design, technical, and structural elements of one project or a set of related projects. Serves four purposes: Officially describes the project. Validates the spec developer’s understanding of the project and its environment. Helps keep all team members consistent. Provides a reference for the next developer.
Who Should “Own” the Spec? Someone, or else it will gather dust. Depends on your organizational structure. Usually the spec’s developer, the person most familiar with it. Consider making spec ownership part of a job description. Make spec handoff a formal step when the owner changes jobs.
Some Attributes of A Good Spec Short - 100-page specs are impressive but no one reads or maintains them. Flexible - Exceptions always occur. Add a deviation procedure. Organizationally supported - Any group affected by the spec should have a say. Controlled - There’s an owner, and a clear hand-off procedure when the owner leaves.
More Attributes of A Good Spec Technically oriented - A spec isn’t a style guide, though it can include a style guide. Assume that your writers know grammar. Technically supported - Anything that can be controlled by a template should be. Market-oriented - Your goal should be to create effective material that supports the products, not to win STC awards.
What Goes Into A Spec? In general: Administration. Project, configuration, audience descriptions. Information structure. Navigation. Interface features. Tool and miscellaneous technical specs. Development and record-keeping procedures. Miscellaneous.
Points to Consider Are there specs? If so, who wrote them? When? Where are they? Are they adhered to? Is there any penalty for not adhering to them?
Standards Issues In General Structure and Appearance Coding Other
In General Standardize anything you can. Make the standards “invisible” if possible, like Flare’s master stylesheet. Publicize the standards, train people on their use, and made adherence mandatory. Major points on which to set standards…
Structure and Appearance Template-based structure – Discussed shortly. Styles – Discussed shortly. Special effects – Minimize or eliminate. Overpower content, irritating, troublesome when moving between different formats. But you may not win awards without them.
Coding Develop in-house expertise on the formats, tools, and conversion procedures. Budget for training and conferences. “Stay between the lines.” Use tools correctly and avoid “hacks”. “Hacks” usually involves breaking syntax rules.
WinHelp Watermark Hack This code: Produced this:
WinHelp Watermark Hack Which was “fixed” by the HAT’s HTML conversion tools to this:
Coding Develop a policy to avoid code-level work. Slow. Quirky. Error-prone. Technically demanding, which narrows your hiring and contracting pool. Replace local formatting with styles or a CSS. Use character styles for text enhancement.
Coding Design for flexibility. Use font sets for cross-platform output. Look at using relative units like % or ems in place of absolute units like pixels or inches. Validate your code. Not necessary, but a good way to check the cleanliness of your authoring tool’s output. See www.flfsoft.com/html/html_validators.html Get into the habit of creating clean code.
Topic Length – Single-Screen Pro: Easy to use. Cons: Hard to create. Hard to maintain. Hard to enforce if material will be translated. Impossible to enforce if window is resizable.
Topic Length – Multi-Screen Pro: Solves all the “single-window” cons. Cons: No writing discipline required of developers. May need bookmarks/link anchors, increasing project complexity.
Other Writing – Discussed shortly. Tools – Discussed shortly. Placeholders and conditionality. Indexing. Other?
Points to Consider What standards are in effect in your company? Are they known? Followed? Who wrote them? Controls them?
Information Design Issues Information Types Information Output Issues Legacy Content History Information Conversion Direction Information Type Structure
Information Types Define your information types and outputs. The types of information you create regularly – concepts, task description, reference, show-me, troubleshooting, etc. The bases of your topic templates. Templates will consist of general elements, like headings, bulleted lists, etc., plus tool-specific elements, like Flare togglers.
Current Types? Before starting, ask: Do we have information types now? Does anyone know what they are? Do content providers follow them? If not, are they amenable? Do they need training? Any tool changes required by providers? Any “practice” barriers to change? Without asking, you can waste your effort.
Information Output Issues Define your outputs. To define the tool features to use for each one. Also to determine if any template elements will not convert well or at all to different outputs. Will expanding text online convert to hard-copy? Use hyperlinks or cross-references to create links for output to be created as online and hard-copy?
Legacy Content History Determine when it was created, if you can. Knowing the trends at that time may explain why things are the way they are. Determine the authoring tool and techno-logy history, if you can. May explain problems going between tools or tool versions.
Information Conversion Direction For the outputs you identified, what’s your conversion direction? Hard-copy to online or vice versa. Helps determine what conversion problems you can ignore or have to fix.
Information Type Structures Based on your analysis, specify required and optional elements and their structure for each type you defined. For example, a task type has or may have: Heads and subheads Text Bulleted and numbered lists Graphics Related topics lists, etc…
Conversion Problems Consider elements that may depend on the tool, output, or conversion direction. Browse buttons in WinHelp. Hard-copy glossary that has a different form in HTML Help vs. WebHelp created using Flare. This will help you determine: Whether to drop or retain such elements. Cross-format conversion features, and tools.
Information Type Structures You now have a standard structure for each information type. Elements and their sequence, hierarchy, and restrictions. This doesn’t yet define how the elements will actually look – the styles.
Information Type Structures For example, you might define the “task” type with these elements and rules. Always starts with a title in Heading 1 style. Title followed by text in Normal style. Can include bulleted or numbered lists, etc. Then a “Syntax” sub-head in Heading 2 style. Can include bulleted or numbered lists, etc. Then text in Normal style. And so on...
Information Type Structures Each type’s design should also specify: Mandatory and optional elements. Mandatory element sequences. Things not to do, such as local formatting or using tables to control element alignment.
Sources of Content Issues Sources of Content
Sources of Content Why it matters… We’d like this raw material to be usable in our outputs with no cleanup. This depends on the content source. Three main sources: Traditional – From the doc group. User-generated – In wikis, tweets, etc. User-generated – In traditional tools like Word.