Structured Writing 9781937434571, 9781937434564

Table of contents :
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