Structured Writing

Description

Structured writing has never been more important or more confusing. We keep trying to do more and more with content, but we give ourselves less and less time to do it. Structured content can help keep your rhetoric on track and your processes efficient. But how does it do that and what is the relationship between rhetoric and process? It is easy to get lost in sea of acronyms and buzz words: semantics, XML, metadata, DITA, structure, DocBook, hypertext, Markdown, topics, XSLT, reuse, LaTeX, silos, HTML. Structured Writing cuts through the noise, explaining what structured writing is (you have been doing it all along) and how you can use different structures to achieve different purposes. It focuses on how you can partition and manage the complexity of the content creation process using structured writing techniques to ensure that everything is handled by the person or process with the skills, time, and resources to handle it effectively. Most importantly, this book shows you how the right structured writing techniques can improve the quality of your content and, at the same time, make your content processes more efficient without sacrificing quality for efficiency or vice versa. There are so many options available in the structured writing space today. This book will show you where each of them fits and help you choose the approach that is optimal for your content. About the Author Mark Baker is the author of Every Page is Page One: Topic-based Writing for Technical Communication and the Web as well as other books on content and content technologies and dozens of articles on technical communication, content strategy, and structured writing. He has worked as a technical writer, tech comm manager, director of communications, programmer, copywriter, and consultant and has spoken frequently at industry conferences. He has designed, built, and used multiple structured writing tools and systems, including the one used to write this book. Mark blogs at everypageispageone.com and tweets as @mbakeranalecta. Preface Introduction 1. Rhetoric 2. Process 3. Complexity 4. Partitioning complexity 5. The complex relationship of process and rhetoric 6. Complexity is complex 7. How this book is organized I. Structured Writing Domains 1. How Ideas Become Content 1.1. From ideas to dots 1.2. The three domains 2. Writing in the Media Domain 2.1. Partitioning font information 3. Writing in the Document Domain 3.1. Context and structure 3.2. Constraining document structure 4. Writing in the Subject Domain 4.1. Using subjects to establish context 5. The Management Domain: an Intrusion 5.1. Including boilerplate content 5.2. An alternative approach in the subject domain 5.3. Hybrid approaches II. Process, Rhetoric, and Structure 6. Partitioning Complexity 6.1. Desktop publishing 6.2. Style sheets 6.3. Content management systems 6.4. Markup languages 6.5. Algorithms 6.6. Partitioning and roles 6.7. Quality and rhetoric 6.8. Build quality into the process 6.9. Towards a more effective partitioning of the content system 7. Rhetorical Structure 7.1. Conforming existing content to a type 7.2. Presentation-oriented rhetorical structures 7.3. Rhetorical meta-models 7.3.1. Meta-models vs generic models 7.4. Making the rhetorical structure explicit 7.5. Structure and repeatability 7.6. Rhetoric and process 8. Information Architecture 8.1. Information architecture: past and present 8.2. Top-down vs. bottom-up information architecture 9. Writing 9.1. We write better for machines than we do for humans 9.2. Structure, art, and science 9.3. Contra-structured content 9.4. Constraints versus usability 9.5. Functional lucidity 9.6. Simplicity and clarity III. Algorithms 10. Separating Content from Formatting 10.1. Separate out style instructions 10.2. Separate out formatting characters 10.3. Name your abstractions correctly 10.4. Make sure you have the right set of abstractions 10.5. Create containers to provide context 10.6. Move the abstractions to the containers 10.7. Separate out abstract formatting 11. Processing Structured Text 11.1. Two into one: reversing the factoring out of invariants 11.2. Restoring style information 11.3. Rules based on structures 11.4. The order of the rules does not matter 11.5. Applying rules in the document domain 11.6. Processing based on context 11.7. Processing container structures 11.8. Restoring factored-out text 11.9. Processing in multiple steps 11.10. Query-based processing 12. Single Sourcing 12.1. Basic single sourcing 12.2. Differential single sourcing 12.3. Differential organization and presentation 12.4. Conditional differential design 12.5. Primary and secondary media 12.6. Single sourcing vs single format 13. Reuse 13.1. Fitting pieces of content together 13.2. Common into variable 13.3. Variable into common 13.4. Variable into variable 13.4.1. Using IDs 13.4.2. Using keys 13.5. Common with conditions 13.6. Factor out the common 13.7. Factor out the variable 13.8. Assemble from pieces 13.9. Combining multiple techniques 13.10. Content reuse is not a panacea 13.10.1. Rhetoric traps 13.10.2. Cost traps 13.11. Alternatives to reuse 14. Generated Content 14.1. Categorization 14.2. Tables of contents 14.3. Lists 14.4. Collections and selections 14.5. Content queries 14.6. Personalized content 14.7. Audit reports 14.8. Reuse versus generation 15. Extract 15.1. Tapping external sources of content 15.2. Extracting information created for other purposes 15.3. The diversity of sources 16. Merge 17. Modeling 18. Linking 18.1. Subject affinities 18.2. Subject affinities in the media domain 18.3. Subject affinities in the document domain 18.4. Subject affinities in the management domain 18.5. The problem with IDs and keys 18.6. Relationship tables 18.7. The problem with relationship tables 18.8. Conditional linking 18.9. Subject affinities in the subject domain 18.10. Finding resources to link to 18.11. Different domain, different algorithm 19. Publishing 19.1. The rendering algorithm 19.2. The encoding algorithm 19.3. The formatting algorithm 19.4. The presentation algorithm 19.5. Differential presentation algorithms 19.6. Presentation sub-algorithms 19.6.1. The linking algorithm 19.6.2. The content generation algorithm 19.7. The synthesis algorithm 19.8. Differential synthesis 19.9. Synthesis sub-algorithms 19.9.1. The reuse algorithm 19.9.2. The content-generation algorithm 19.9.3. The extract algorithm 19.9.4. The merge algorithm 19.9.5. The modeling algorithm 19.10. Deferred synthesis 19.11. Combining algorithms 19.12. Architecture of a publishing tool chain 20. Active Content IV. Structures 21. Content as Data 21.1. Flat versus hierarchical structures 21.2. Annotating blocks 21.3. Agreeing on names 21.4. Different rules for intermediate languages 21.5. Secondary structures of interpretation 21.6. Child blocks versus additional annotations 22. Blocks, Fragments, Paragraphs, and Phrases 22.1. Semantic blocks 22.2. Structural blocks 22.3. Semantic blocks in the subject domain 22.4. Information-typing blocks 22.5. Rhetorical blocks 22.5.1. Granularity 22.6. Fragments 22.7. Paragraphs and phrases 22.7.1. Phrases 23. Wide Structures 23.1. Tables 23.2. Alternatives to tables 23.2.1. Alternate presentations 23.2.2. Subject-domain structure 23.2.3. Record data as data 23.3. Computer code 23.4. Pictures and graphics 23.4.1. Inline graphics 24. Subject-Domain Structures 24.1. Keep it simple and lucid 25. Metadata 25.1. The recursive nature of metadata 25.2. Where should metadata live? 25.3. Ontology 26. Terminology 26.1. Top-down terminology control 26.2. Bottom-up terminology control 26.3. Creating and maintaining a taxonomy 26.3.1. Centralized versus distributed allocation of complexity 26.3.2. Stop lists 27. Relevance 27.1. Being relevant 27.2. Showing relevance 27.3. Showing relevance to algorithms 28. Composable Structures 28.1. Combining the pieces 28.2. Combining structures 28.3. Stylistic and rhetorical compatibility 28.4. Narrative flow 29. Conformance 29.1. Completeness 29.2. Consistency 29.3. Accuracy 29.4. Semantic constraints 29.5. Entry validation constraints 29.6. Referential integrity constraints 29.7. Conformance to external sources 29.8. Conformance and change 29.9. Design for conformance V. Languages 30. Markup 30.1. Markup vs. regular text 30.2. Markup languages 30.2.1. Concrete markup languages 30.2.2. Abstract markup languages 30.2.2.1. Instances of abstract markup languages 30.2.2.2. Concrete languages in abstract clothing 30.2.2.3. The ability to extend 30.2.2.4. The ability to constrain 30.2.2.5. Showing and hiding structure 30.2.3. Hybrid languages 30.2.3.1. Instances of hybrid markup languages 31. Patterns 31.1. Design implications 32. Lightweight Markup Languages 32.1. Markdown 32.2. Wiki markup 32.3. reStructuredText 32.4. ASCIIDoc 32.5. LaTeX 32.6. Subject-domain languages 33. Heavyweight Markup Languages 33.1. DITA 33.2. DocBook 33.3. S1000D 33.4. HTML 33.5. Subject-domain languages 34. Extensible and Constrainable Languages 34.1. XML 34.2. ReStructuredText 34.3. TeX 34.4. SAM 34.5. DocBook 34.6. DITA 34.6.1. Basics of the DITA architecture 34.6.2. Specialization 34.6.3. Limits on rhetorical constraint 34.7. SPFE 35. Constraint Languages VI. Management 36. Content Management 36.1. The location of metadata 36.2. Hybrid approaches 36.3. Alternate repositories 36.4. Multiple repositories 36.5. Making content manageable 36.5.1. Managing structured writing assets 37. Collaboration 37.1. Partitioning collaboration 37.2. Dealing with diverse collaborators 37.3. Wikis 37.4. Management-domain structured writing 37.5. Bridging silos 38. Avoiding Duplication 38.1. The scale of duplication 38.2. Duplication of information versus duplication of text. 38.3. Duplication and the level of detail 38.4. Duplication in less structured contexts 38.5. Localizing duplication detection 38.6. Reducing duplication through consistent content models 38.7. Reducing duplication through consistent quality 38.8. Reducing the incentive to create duplicate content 38.9. Less formal types of duplication detection 38.10. Reducing duplication by merging sources 38.11. Duplication and the structure of content 38.12. Detecting duplication before and after authoring 38.13. Optimize the whole, not the parts 39. Auditing 39.1. Auditing the definition of the content set 39.2. Assessing completeness 39.3. Avoiding contamination 39.4. Maintaining integration 39.5. Making content auditable 39.6. Facilitating human review 40. Change Management 40.1. Out with the old, in with the new 41. Repeatability 42. Timeliness 42.1. Algorithms and timeliness 42.2. Process and timeliness 43. Translation 43.1. Avoiding trivial differences 43.2. Isolating content that has changed 43.3. Continuous translation VII. Design 44. System Design 44.1. Identifying complexity 44.1.1. Current pain points 44.1.2. Unrealized possibilities 44.1.3. What's working now 44.1.4. Complexity that affects others 44.1.5. Communication overhead 44.1.6. Your style guide 44.1.7. Change management issues 44.1.8. What's coming down the road 44.2. Partitioning and directing complexity 44.2.1. Partitioning the writing task 44.2.2. Partition towards expertise 44.2.3. Focus on complexity, not effort 44.2.4. Indivisible complexity 44.2.5. Subtract current tool complexity 44.2.6. Avoid tool filters 44.3. Selecting domains 44.4. Selecting tools 44.5. Counting the costs and savings Index A. Copyright and Legal Notices