DocTrain East, October 19, 2007Presentation Transcript
Painless XML Authoring? How DITA Simplifies XML Bob Doyle [email_address] [email_address] 617-876-5676 Skype: bobdoyle
A brief poll. Who’s heard of…
Structured writing? Information Mapping?
Task-oriented Documentation? vs. ?
Minimalism? John Carroll?
Single-source publishing? vs. Reuse?
Component Content Management?
Bob Horn, John Brockmann, JoAnn Hackos, Ginny Redish, Ruth Clark?
All heard of DITA?
Topics: Concept, Task, and Reference
DITA Open Toolkit
DITA is Simplified XML
A brief surevy of tools
PTC Arbortext (Epic)
Word to DITA (in.vision, Info Mapping)
XML Spy, oXygen
Heard of me? Ph.D. Astrophysics, Harvard, 1968 Collaborative Observing Program, NASA Skylab 1970-72 Super8 Sound, 1973-78 Merlin and 5 other computer games– 1977-81 iXO Telecomputer – 1980-87 MacPublisher – 1984-1987 Digital Video Editor, New Media Magazine -1993-1999
Parker Brothers Games
Computer-initiated dialogues (AI)
Yes, No, Help, Repeat keys
“ Operators are standing by”
Stock trades, airline reservations, bill paying.
Powered from phone line
Venture capital $13 million
Never developed the backend database services
Huge NOL carry-forward
First Desktop Publishing Program
11 th Certified Mac Developer
Shipped in 1984
Laserwriter in 1985
First “spot color” text on Apple Imagewriter
First rotated text/gaphics
Sold 20,000 copies
Sold to Letraset in 1987
Doing What Recently CEO, skyBuilders.com Editor, CMS Review related websites – CMS Wiki, CMS Forum, CMS News, CMS Calendar, CMS Glossary, CMSML, CMS Boston, Open Internet Lexicon, TaxoTips Founder, CM Professionals Contributing Editor, EContent Magazine Founder, DITA Users related websites – DITA Infocenter, DITA News, DITA Newsletter, DITA Blog, DITA Wiki, and DITA Tutor
The First Podcast - 2003
Christopher Lydon (NPR’s “The Connection”)
Lydon’s “Open Source” Show
6 columns per year
XML Authoring Tools Review
12 online columns per year
Joined OASIS - 2006
Organization for the Advancement of Structured Information Standards
Member – DITA Technical Committee
Member – Learning and Content SC
Member – Help SC
Observer – Translation SC
Member – Editorial Board
Organizer – Boston DITA User Group
DITA Users – Launched in March
DITA Users is an international membership organization
~400 members from 21 countries.
Members learn topic-based structured writing.
Author DITA with DITA Storm browser-based editor
Deliverables for web (XHTML), print (PDF), Help (Eclipse) from single-source documents.
Members have a personal workspace folder.
Finished work on web to show colleagues and clients.
Member directory has contact information.
Discounts on major DITA conferences, on tools (?), on
DITA tutorials and workshops, and on the DITA Report.
DITA Infocenter – Launched April
DITA Infocenter is Eclipse-based Online Help
DITA Architectural Specification (1.0 and 1.1)
DITA Language Specification (1.0 and 1.1)
Open Toolkit User Guide (1.3.1)
Index of keywords
Table of contents
Generated from DITA files with Open Toolkit
DITA News – Launched June
Aggregates blog posts from DITA bloggers.
Extensive listings of DITA tools from A to Z.
Events calendar with conference listings,
Websites, Publications, Webinars.
Glossary of DITA terms.
Content syndicated to other websites
Single-source publishing tools.
DITA Blog – Launched July
Anyone may join
RSS feeds syndicate to DITA News
DITA Wiki – Launched July
Resources with comments and discussions.
Mediawiki software (Wikipedia)
Architectural and Language specifications
Vendors and Products
Edited directly by the vendors
People section - major DITA players
Glossary of terms
DITA Newsletter – Launched September
Monthly summary of DITA news
Industry mailing list for press releases.
DITA Mentor Awards
Next month’s events listings
Member discount offers
DITA Tutor – Launched September
Learning management system (Moodle LMS)
Self-paced online tutorials
Instructor-led online workshops
Some with audio recording
Courses in DITA techniques
Certificates of completion.
DITA User Groups
Encouraging remote attendance
Recording meeting presentations
Archiving to DITA Tutor
Possibly repurpose as eLearning
What collaboration tools should we use?
Structured Writing – 1960’s and 70’s
Structured writing requires an analysis of content and a reorganization into the smallest possible coherent topics. Decades of research on such analysis and organization have been done by Information Mapping™ , who identified common document types, information types, and information blocks (chunks or topics) in use in education and commerce.
The reduction in structured authoring time may be offset by the increased time needed to analyze the content and break it into reusable chunks. There is no doubt that granular content, with well-defined purposes for each paragraph and sentence, is easier to author than linear content. But you may need skilled (i.e., more expensive) information developers to chunk your material.
Task-oriented Documentation – 1980’s
Task-oriented docs have replaced system-oriented or product-oriented docs - the old comprehensive user manual.
ROI - The number of calls per month to the help desk on a product will almost certainly change when product documentation is task oriented and minimalist. And task-oriented content can feed directly into help-desk scripts.
Minimalism – 1990’s
Minimalism aims to provide just what the impatient user is looking for. Remember, the web surfer is always just one click away from going to your competition's website. Your job is to strip away unnecessary content and get to the point. You can measure the return by pre-testing and post-testing content that has been re-architected along minimalist principles.
Minimalism appears to promise reduced costs for the simple reason that there is so much less content in well-prepared minimalist material. But it takes talented people to write succinct, action-oriented procedures that get users to understand quickly what they need to know and successfully do it. And minimalist material is best when it is tested for effectiveness, adding to costs.
Single-source Publishing – 1990’s
The original definition of single-source publishing was providing multiple output formats like Web, Print, and Online Help from the original documents.
When you have one source for each piece of content, you get the astonishing ability to change it in one place and have the change propagate everywhere. A product name change becomes much more manageable. Your business-critical marketing messages are standardized everywhere. Some call single source a "single source of truth" because you are assured that your customers are not getting mixed messages that can confuse them, reduce sales, and increase the need for tech support.
Single-source plus Reuse
Reusable content has a single source, of course, but reuse generally refers to content originally developed for one context that can be reused in another. This requires content that is topic-based and written for reuse by avoiding explicit references to context.
The cost savings associated with reuse of content increase greatly when your content goes through a workflow with distinct review and approval stages, for example legal approval. Content that is reused generally can avoid all or most of the extra steps in the workflow that involve accuracy of content. You will still need design approval of the in-context appearance of the reused content.
Component Content Management
The latest buzzword in CMS is "component." Most web content management (WCMS) segment content at the web page. While this may be adequate for simple websites written by one or a few content contributors, it is not acceptable for websites whose pages act as portals to diverse kinds of interactive content.
Modern corporate pages pull content in from multiple sources. Each content block is filled with a content component managed independently of all the other blocks on the page. A component has its own versioning and scheduling, its own writers, reviewers, and approval process.
A topic is a unit of information with a title and some form of content, short enough to be specific to a single subject or answer a single question, but long enough to make sense on its own and be authored as a unit.
A topic aims to be context-free, so it contains no links to other topics.
In DITA, the topic is the basic unit of authoring and of reuse.
A topic is a content component
Why Concept, Task, and Reference?
Remember Macintosh doc guidelines?
Learning MacPaint, Using MacPaint, the MacPaint Reference.
Eight top XML Editors were studied Chosen from 6 5 i n CMS Review Editor Listings P ublished in the June issue of EContent Magazine Extended version - XML Editors Report
Which Editors Do You Use?
A quick poll of your experience
The XML Editors Report
Personal use license
One year of release versions
Online consulting included
Screen share to look at interfaces
CM Pros Best Practices
Open Source (and Open Documents)
Online (ASPs and Web Services)
AJAX, Web 2.0
Information Architecture and Content Management.
Two Kinds of Information Architecture
IA of document sets, books in a library, a website, the World Wide Web – organization, cataloging, metadata tagging, accessibility, findability.
IA of a single document - page structure, allowed navigation elements and reusable content components.
Defining Content Management
What is a CM System?
What Is Content Management?
What Is Content?
What is a CM System?
It is humans using computers and software to assist in managing content.
It has two main parts:
The user interface.
The database (content repository).
Everything else is magic middleware.
It helps manage the content lifecycle.
What Is Content Management?
Content management is the whole process from creation and capture of original content to the delivery of different versions to many publishing channels:
The Content Lifecycle
Brown Television (BTV) Doug Liman
Hi-8 Users Group Funded Videomaker Magazine, Hi-8 Group became Desktop Video Group in 1992
HRTV and Quad Sound Harvard-Radcliffe Film Workshop was in the basement of Holmes Hall (North/Pforzheimer House) where the old Radcliffe Radio Station and Morse Music Library were located. In the mid-80’s it became HRTV and the radio broadcast booth and adjoining sound rooms became Quad Sound Studios.
Other CMS Review Sites
CMS Review Glossary
Finding a CMS
The CMSML project at CMS Review and CM Pros
Select two CMS or enter search terms to find CMS that match your criteria. The directory is a faceted classification scheme. Click compare to get the results below...
Nearly 1000 members in 2006
Website (7/10 Google PageRank)
Benefits - Mail, Member Directory
Glossary, Resource Library, Calendar
Communi ties - CMSML, DITA, Global
News, Blog aggregation
CM Pros Member Directory
CM Pros Calendar
CM Pros Videos
Eighty hours of video from Gilbane Conferences, IA Summit, OSCOM, Bloggercons at Harvard.