DITACMS Content Creation Issues: A Case Study

1
DITA-CMS Content Creation Issues A Case Study

• Yosef Symonds
• 4th June 2007

2
Aim

• Highlight key concepts of DITA for BigBand
  Networks
• Pinpoint key authoring implementation issues
• Share decision considerations for these issues

3
Preparing Common Ground

• CMS modules
• authoring
• content management (engine)
• publication
• review
• translation
• XML authoring
• DTD
• Open architecture
• Single sourcing

4
CMS Components

• A Content Management System (CMS) is an
  integrated system with the major components shown
  below

Content Authoring Tools
Content Database Management
Content Publishing Tools
Workflow Management Tool
Translation Management Tool
5
Why CMS in General?

• Multiple benefits from CMS
• typically one big benefit decides
• Uniformity of content structure
• DTD
• Uniformity of content formatting
• global style sheets
• Efficiency of formatting
• Independence of open architecture
• Content permissions (and library functions)
• Translation efficiency
• Content reuse/reassembly support

6
Why CMS for BigBand?

• What was lacking in pre-CMS BigBand picture?
• problem coping with increasing number of
  documents
• problem coping with content reuse across
  documents
• difficulty with document assembly management
• difficulty keeping format in synch
• uneasiness with proprietary content format
• BigBand characteristics suggesting reuse
• develops multiple products
• provides solutions not products

7
Example Content SWB 4.5 Release
BMR System Specifications Ver 2.x
Legal and Front Matter Boilerplates
SWB 4.5 Solution Specifications
SWB 4.5 Solutions Guide
BMR Platform HL S/W Applications Ver 2.x User
Guide
NMS Ver 4.5
BMR Installation Configuration Guide
BME Installation Configuration Guide
8
What is DITA? Super DTD

• Darwin Information Typing Architecture
• More than DTD (set)
• content tagged by information type
• content organized into docs by maps
• extensions according to specialization rules
• compare custom, DocBook

9
Authoring Specialization
Authoring
Structured Authoring
XML Authoring
DITA Standard Authoring
DITA Specialized Authoring
10
What is DITA? Topics and Maps

• Topic-based info model
• departure from book paradigm
• Concept, Task, Reference topics
• reuse focus implemented with maps
• Maps
• document definitions representing relationships
  between topics by organizing references to those
  topics
• tables of content for mature documents
• outlines of content for new documents

11
Task Topic - Basics
12
Task Topic - Extras
13
What is DITA? Processing Methodology

• Specialization and Processing
• DITA specializations
• structural specialization - create new topic
  types
• domain specialization - create new semantic
  elements for domain-specific vocabularies
• Included domain specializations
• typography
• programming
• software
• user interface
• DITA Open Toolkit
• automated publishing process

14
Why DITA?

• Source (not publication) oriented
• Match for SMEs review supportive
• Centrality of procedural content
• meeting core challenge head-on
• rich information modeling
• Document assembly oriented
• Why NOT DITA?
• Requires more disciplined authoring,
  pre-planning, management
• Supporting S/W not as mature as for DocBook

15
What is a Topic?

• Related to book component?
• example Heading level 3 and higher?
• convenient for migration
• Related to screen output?
• one screen worth?
• No refocus from published format to source
• logical, conceptual, criteria for content
• Not too small check independence
• Not too large check reuse and link specifics
• Check set of outputs for special requirements

16
Topic Title Temptations

• Scope of title
• temptation to continue book paradigm
• duplication and ambiguity
• resolve according to scope
• Naming conventions of title
• temptation to continue description cue about

17
What is Status in DITA-Speak?

• Dual properties of status
• Distribution and Authority properties of
  documents?
• distribution tells for whom
• authority tells who authorized and how complete
  it is
• But status of what? documents? source content?
• source content comprises topics / maps
• Proposed BBND statuses
• approved
• customer draft
• internal draft
• information only
• not approved

18
DITA Topic/Doc Status Definitions 1

• Approved
• Customer Draft
• set of reviewers was less than that required for
  approval AND/OR the review itself by one or more
  reviewers was incomplete
• Internal Draft
• topic has at least initial SME approval
• map has at least initial PM approval
• in the document
• each topic is at least internal draft
• the map is at least internal draft
• Information Only
• any document composed only of Approved or
  Customer Draft topics BUT
• there is no Approved or Customer Draft map for
  this document
• Not Approved

19
DITA Topic/Doc Status Definitions 2
20
Argumentative Quick Procs

• Structure in topics supports data mining and
  reconstruction
• Task topics
• Reference topics
• Quick proc(edure)s
• consider audience
• consider published format
• CLI command reference
• challenge tailor superset to specific release
• CLI command reference implementation
• apply conditions to standard Reference topic
• apply conditions to specialized Reference topic
• use report utility on topic
• maintain externally as master DB

21
Who Authors and How?

• Who?
• Technical writers?
• limited and limiting
• Others?
• training
• product and project managers
• customer support
• How?
• Full-featured (like tech pubs) or lite XML
  editor
• Word plug-in
• Structured ( disciplined unstructured!) Frame
• WordML and unstructured FrameMaker

22
Conclusions DITA Advantages

• Topic orientation
• Ease of reuse and document assembly
• Simplified maintenance thru specialization
• Review streamlining
• Data mining opportunities from structure
• Fast-growing industry support

23
Conclusions DITA Authoring Challenges

• Special author perspective for DITA
• new, highly disciplinary, anticipatory,
  publishing environment
• new writer paradigms for authoring reviewing
  managing publishing
• rethinking and opportunities
• learning curves
• Defining and naming topics
• Giving meaning to status
• Legacy migration complexity
• Accommodating part-time contributors
• Thank you for participating!
• Yosef Symonds
• yosef.symonds_at_bigbandnet.com