| |
| |
| Acknowledgments | |
| |
| |
| About the Authors | |
| |
| |
| Introduction | |
| |
| |
| |
| Writing In Dita | |
| |
| |
| |
| Topic-Based Writing in DITA | |
| |
| |
| Books, Topics, and Webs of Information | |
| |
| |
| Advantages of Writing in Topics for Writing Teams | |
| |
| |
| Writers Can Work More Productively | |
| |
| |
| Writers Can Share Content with Other Writers | |
| |
| |
| Writers Can Reuse Topics | |
| |
| |
| Writers Can More Quickly Organize or Reorganize Content | |
| |
| |
| Reviewers Can Review Small Groups of Topics Instead of Long Books | |
| |
| |
| DITA Topic Types | |
| |
| |
| Task Orientation | |
| |
| |
| Task Analysis | |
| |
| |
| Minimalist Writing | |
| |
| |
| Know Your Audience | |
| |
| |
| Remove Nonessential Content | |
| |
| |
| Focus on User Goals, Not Product Functions | |
| |
| |
| To Wrap Up | |
| |
| |
| Topic-Based Writing Checklist | |
| |
| |
| Task analysis form | |
| |
| |
| |
| Task Topics | |
| |
| |
| Separate Task Information from Conceptual or Reference Information | |
| |
| |
| Write One Procedure per Topic | |
| |
| |
| Create Subtasks to Organize Long Procedures | |
| |
| |
| Task Components and DITA Elements | |
| |
| |
| Titling the Task | |
| |
| |
| Introducing the Task: <shortdesc> | |
| |
| |
| Adding More Background Information: <context> | |
| |
| |
| Describing Prerequisites: <prereq> | |
| |
| |
| Writing the Procedure: <steps> and <steps-unordered> | |
| |
| |
| Concluding the Task: <example>, <postreq>, and <result> | |
| |
| |
| Task Topic Checklist | |
| |
| |
| |
| Concept Topics | |
| |
| |
| Describe One Concept per Topic | |
| |
| |
| Create a Concept Topic Only if the Idea Can't Be Covered More Concisely Elsewhere | |
| |
| |
| Separate Task Information from Conceptual Information | |
| |
| |
| Concept Components and DITA Elements | |
| |
| |
| Titling the Concept Topic: | |
| |
| |
| Introducing the Concept Topic: <shortdesc> | |
| |
| |
| Writing the Concept: <conbody> | |
| |
| |
| Organizing the Concept: <section> | |
| |
| |
| Adding Lists: <ol>, <ul>, <sl>, and <dl> | |
| |
| |
| Including Graphics: <fig>, , and <image> | |
| |
| |
| Highlighting New Terms: <term> | |
| |
| |
| To Wrap Up | |
| |
| |
| Concept Topic Checklist | |
| |
| |
| |
| Reference Topics | |
| |
| |
| Describe One Type of Reference Material per Topic | |
| |
| |
| Organize Reference Information Effectively | |
| |
| |
| Format Reference Information Consistently | |
| |
| |
| Reference Components and DITA Elements | |
| |
| |
| Titling the Reference topic | |
| |
| |
| Introducing the Reference Information: <shortdesc> | |
| |
| |
| Organizing the Reference Information: <section> | |
| |
| |
| Creating Tables: <table>, <simpletable>, and <properties> | |
| |
| |
| Adding Lists: <ul> and <dl> | |
| |
| |
| Creating Syntax Diagrams: <refsyn> and <syntaxdiagram> | |
| |
| |
| To Wrap Up | |
| |
| |
| |
| Short Descriptions | |
| |
| |
| The <shortdesc> Element | |
| |
| |
| How the Short Description Is Used | |
| |
| |
| Guidelines for Writing Effective Short Descriptions | |
| |
| |
| Briefly State the Purpose of the Topic | |
| |
| |
| Include a Short Description in Every Topic | |
| |
| |
| Use Complete, Grammatical Sentences | |
| |
| |
| Don't Introduce Lists, Figures, or Tables | |
| |
| |
| Keep Short Descriptions Short | |
| |
| |
| Short Descriptions for Task, Concept, and Reference Topics | |
| |
| |
| Task Topic Short Descriptions | |
| |
| |
| Concept Topic Short Descriptions | |
| |
| |
| Reference Topic Short Descriptions | |
| |
| |
| Writing Short Descriptions for Converted Content | |
| |
| |
| The <abstract> Element | |
| |
| |
| Using More DITA Elements in the Topic Introduction | |
| |
| |
| Including Multiple Short Descriptions | |
| |
| |
| To Wrap Up | |
| |
| |
| Short Description Examples | |
| |
| |
| Short Description Checklist | |
| |
| |
| |
| Architecting Content | |
| |
| |
| |
| DITA Maps and Navigation | |
| |
| |
| DITA Map Structure | |
| |
| |
| Relationships Between Topics | |
| |
| |
| Information Organization | |
| |
| |
| Information Modeling | |
| |
| |
| Benefits of Information Modeling | |
| |
| |
| Building Information Models | |
| |
| |
| Bookmaps | |
| |
| |
| Submaps | |
| |
| |
| DITA Map Ownership | |
| |
| |
| Include Relationship Tables in DITA Maps | |
| |
| |
| Override Topic Titles and Short Descriptions | |
| |
| |
| Navigation Titles | |
| |
| |
| Short Descriptions | |
| |
| |
| Provide Unique Short Descriptions for Reused Topics | |
| |
| |
| Provide Short Descriptions for Links to Non-DITA Content | |
| |
| |
| Suppressing Topics from the Table of Contents | |
| |
| |
| Suppressing Content from PDF Output | |
| |
| |
| Suppressing Content from HTML Output | |
| |
| |
| To Wrap Up | |
| |
| |
| Navigation and DITA Maps Checklist | |
| |
| |
| |
| Linking | |
| |
| |
| Hierarchical Links | |
| |
| |
| Inline Links | |
| |
| |
| Link to Prerequisite and Postrequisite Information | |
| |
| |
| Avoid Inline Links to Tables and Figures in a Topic | |
| |
| |
| Create Inline Links to Repeated Steps | |
| |
| |
| Create Inline Links to High-Level Tasks | |
| |
| |
| Control How Links Are Displayed | |
| |
| |
| Related Links | |
| |
| |
| Relationship Tables | |
| |
| |
| Implementing Relationship Tables | |
| |
| |
| Collection Types | |
| |
| |
| Sequence Collection Type | |
| |
| |
| Choice Collection Type | |
| |
| |
| Unordered Collection Type | |
| |
| |
| Family Collection Type | |
| |
| |
| Determining Which Collection Type to Use | |
| |
| |
| Collection Types in Relationship Tables | |
| |
| |
| Links Created with the Importance Attribute | |
| |
| |
| Linking Scope | |
| |
| |
| Local Links | |
| |
| |
| External Links | |
| |
| |
| Peer Links | |
| |
| |
| Relative Paths for Links | |
| |
| |
| Link Testing | |
| |
| |
| To Wrap Up | |
| |
| |
| Linking Checklist | |
| |
| |
| |
| Metadata | |
| |
| |
| Why Is Metadata Important | |
| |
| |
| Types of Metadata | |
| |
| |
| Index Entries | |
| |
| |
| Conditional Processing Attributes | |
| |
| |
| Importance, Status, and Translate Metadata Attributes | |
| |
| |
| Topic Metadata | |
| |
| |
| DITA Map Metadata | |
| |
| |
| Custom Metadata | |
| |
| |
| Metadata Inheritance | |
| |
| |
| To Wrap Up | |
| |
| |
| Metadata Checklist | |
| |
| |
| |
| Conditional Processing | |
| |
| |
| Conditional Processing Attributes | |
| |
| |
| Creating a Conditional Processing Scheme | |
| |
| |
| Example of a Conditional Processing Scheme | |
| |
| |
| Applying Conditional Processing Attributes | |
| |
| |
| Applying Conditions to Content in Topics | |
| |
| |
| Applying Conditions to DITA Maps and Relationship Tables | |
| |
| |
| Excluding and Including Content | |
| |
| |
| Flagging Content | |
| |
| |
| Multiple and Compound Conditions | |
| |
| |
| Multiple Conditions | |
| |
| |
| Compound Conditions | |
| |
| |
| Processing Logic for Multiple and Compound Conditions | |
| |
| |
| Identifying Applied Conditional Values | |
| |
| |
| Testing Your Scheme | |
| |
| |
| Improving Content Retrievability for the Writing Team | |
| |
| |
| To Wrap Up | |
| |
| |
| Conditional Processing Checklist | |
| |
| |
| |
| Content Reuse | |
| |
| |
| Benefits of Reuse | |
| |
| |
| Ways to Reuse Content | |
| |
| |
| Reusing Elements by Using Content References | |
| |
| |
| Conref Attribute | |
| |
| |
| Phrase-Level Reuse | |
| |
| |
| Designated Source Files for Conrefs | |
| |
| |
| Reusing Topics | |
| |
| |
| Copy-to Attribute | |
| |
| |
| Reusing DITA Maps | |
| |
| |
| Reusing Content from Non-DITA Sources | |
| |
| |
| Writing for Reuse | |
| |
| |
| Deciding Which Content to Reuse | |
| |
| |
| |
| Analyze Your Content | |
| |
| |
| |
| Identify Duplicate and Near Duplicate Content | |
| |
| |
| |
| Address the Duplication | |
| |
| |
| |
| Reorganize and Rewrite for Reuse | |
| |
| |
| |
| Implement the Reuse Strategy | |
| |
| |
| Track Your Reuse | |
| |
| |
| To Wrap Up | |
| |
| |
| Reuse Checklist | |
| |
| |
| |
| Converting And Editing | |
| |
| |
| |
| Converting Content to DITA | |
| |
| |
| Conversion Goals | |
| |
| |
| Create a Pilot Team | |
| |
| |
| Conversion Process | |
| |
| |
| |
| Assess the State of Your Content | |
| |
| |
| Content Analysis Worksheet | |
| |
| |
| |
| Plan the Conversion | |
| |
| |
| Scheduling the Conversion | |
| |
| |
| Converting the Content In-House 208or Hiring a Vendor | |
| |
| |
| Staffing Your Conversion Team | |
| |
| |
| Deciding on a Conversion Strategy | |
| |
| |
| Defining your XML Standard | |
| |
| |
| Establishing Graphics Formats | |
| |
| |
| Establishing DITA File Requirements | |
| |
| |
| Deciding What DITA Topic Types You Nee217d | |
| |
| |
| Establishing an Architecture for Your DITA Ma218ps | |
| |
| |
| Handling Special Structures in Your Source Files | |
| |
| |
| |
| Prepare the Content for Conversion | |
| |
| |
| Conversion Workshops | |
| |
| |
| |
| Convert Your Source Files | |
| |
| |
| |
| Address Postconversion Issues | |
| |
| |
| |
| Address <required-cleanup> Elements | |
| |
| |
| |
| Fix Maps and Linking | |
| |
| |
| |
| Improve Topics | |
| |
| |
| |
| Check for Markup Problems and Do Code Reviews | |
| |
| |
| |
| Exploit DITA | |
| |
| |
| |
| Evaluate the Conversion Process | |
| |
| |
| To Wrap Up | |
| |
| |
| Conversion Sizing Table | |
| |
| |
| DITA Conversion Checklist | |
| |
| |
| |
| DITA Code Editing | |
| |
| |
| Code Reviews | |
| |
| |
| Code Review Benefits | |
| |
| |
| Identifying Code Reviewers | |
| |
| |
| Limiting the Scope of the Review | |
| |
| |
| Preparing for Code Reviews | |
| |
| |
| Using Special Style Sheets for Revealing Problems in the Markup | |
| |
| |
| Performing a Code Review | |
| |
| |
| |
| Schedule the Code Review | |
| |
| |
| |
| Submit the DITA Topics for Review | |
| |
| |
| |
| Review the DITA Markup | |
| |
| |
| Common Problems Found in Task Topics | |
| |
| |
| Common Problems Found in Concept Topics | |
| |
| |
| Common Problems Found in Reference Topics | |
| |
| |
| Common Problems Found in All Topic Types | |
| |
| |
| Common Problems Found in DITA Maps | |
| |
| |
| Common Problems Found in Metadata | |
| |
| |
| |
| Discuss Review Findings | |
| |
| |
| |
| Complete the Code Review | |
| |
| |
| Code Reviews for Content Not in Topic Form | |
| |
| |
| To Wrap Up | |
| |
| |
| Code Review Checklist | |
| |
| |
| |
| Content Editing | |
| |
| |
| Defining, Scheduling, and Submitting Content Edits | |
| |
| |
| Defining the Types of Content Edits | |
| |
| |
| Scheduling the Edits | |
| |
| |
| Submitting Content for Edi262ting | |
| |
| |
| Providing Editorial Feedback | |
| |
| |
| Inserting Draft Comments | |
| |
| |
| Inserting XML Comments | |
| |
| |
| Tracking Changes | |
| |
| |
| Comparing Original and Edited Files | |
| |
| |
| Editing the Content in DITA Topics and Maps | |
| |
| |
| Editing DITA Topics | |
| |
| |
| Editing DITA Maps | |
| |
| |
| Editing the Output | |
| |
| |
| To Wrap Up | |
| |
| |
| Content Editing Checklist | |
| |
| |
| Index | |