Consider the Source Structured Authoring for XML-based Documentation

Size: px

Start display at page:

Download "Consider the Source Structured Authoring for XML-based Documentation"

Eric Dalton
6 years ago
Views:

User Services and Web Coordinator College of

1 Consider the Source Structured Authoring for XML-based Documentation Ellen McDaniel Manager of User Services and Web Coordinator College of Engineering North Carolina State University

2 Goal for Documentation: Produce accurate content to help users Navigate a complex and changing computing environment in order to perform critical tasks. Effectively use labs, multiple platforms/oses, application software, via local and remote. Locate information specific to their role (prospective student, new faculty, administrator, etc.) Get information from multiple information channels: print, web, help, portals

3 Problem: Difficult to create, manage, and deliver helpful content to users Unstructured workflows and fuzzy lines of responsibility. Few dedicated documenters. Silos rather than common content repository. Poor content sharing/exchange. Duplication of effort. No single-sourcing. Platform wars. Incompatible apps, formats. Persistent wrong and out-of-date information. One size fits all. No targeted or custom docs. Multiple information channels to deliver to: print, web, help.

4 Why is this problem worth solving? The more good content gets used, the more value is created. - Education of users - Efficient use of resources - Happy user community positive about IT The more bad content is used, the more damage and cost to users and the enterprise. - Miseducation of users - Waste and misuse of resources - Unhappy user community negative about IT Documentation expedites knowledge transfer and acceptance of technology.

5 Example: Supporting the Supporters Help Desk has accurate docs and learns what to tell users. Docs used to train support staff, so reliance on expert staff is reduced. Staff experts taxed less for one-off support. Expert assistance comes through improved information handling and pass-through to documentation. Users read docs and don t have to consult Help Desk.

6 Project: Improve IT Content Development and Delivery Build a repository of IT content from which to develop and produce: General user guides for large but different user groups: students, faculty, administrators Platform-specific content Instructional material for specific courses

7 Extracting Sunbeams out of Cucumbers Author: Jonathan Swift He had been eight years upon a project for extracting sunbeams out of cucumbers, which were to be put in phials hermetically sealed, and let out to warm the air in raw inclement summers. Gulliver s Travels. Part iii. Chap. v. Voyage to Laputa.

8 Can it be done? Companies do it. Methodology and technology exist New emphasis on enterprise content and digital assets management, AKA, the content supply chain. Ubiquitous connection to docs and online content through help systems, web, custom publishing, etc.

9 IT Alchemy: The Sunbeam (Gold) Write once, deliver many. Reuse. Shape up workflow with single-sourcing. Share responsibility for a shared repository. Content ownership not very important. Modularize content. Support chunking and style- and context-neutral authoring. Utility, not poetry. Separate form from content. Promote open standards and platform independence.

10 IT Alchemy: The Cucumber (Base) Structured authoring XML XML editors, apps that roundtrip XML Document Type Definition (DTD) or Schema Output tools: CSS, XSL, XSLT Print and PDF engine File system, database, and/or CMS

11 Structured Authoring Focus on structure and content that is concise, modular, reusable. Formatting separated out, built up-front in a template or applied in post-processing. Elements, not paragraphs. Elements are tagged units of content organized in a nested structure tree. Guided authoring inside tags. Attributes provide metadata about elements used in processing. Content managed as data so you can extract information based on structure and metadata.

12 Structured Authoring

13 Structured Authoring Document Design Types: Unstructured glossary: Free-form typing. Returns to make paragraph breaks. Boldface text to highlight term. Semi-structured glossary. Apply Heading style to term, Para style for definition. Structured glossary. Term and Definition nested in GlossEntry. GlossEntry s nested in a Glossary container.

14 XML and XML Editors Structure elements map to XML tags. XML makes it possible to single-source. Reuse and repurpose the same content for different audiences and deliverables. XML is extensible, not fixed, can be anything. Custom rules and tags (tags with meaning). Open standard, many tools (most free).

15 XML and XML Editors Less complex than parent SGML, which has limited tool selection and does not handle online content. Unlike HTML (i.e., browser will figure it out), XML requires adherence to syntax standards: Well-formed: start/end tags, matching case, attributes in quotes, proper nesting, etc. Minimum correctness for browser/app. Valid: Well-formed and adheres to Document Type Definition (doc s grammatical rules and template, element mapping and sequence).

16 XML and XML Editors

17 XML and XML Editors GUI with built-in tools: Save to XML, import and export DTDs, validate, etc.

18 XML and XML Editors

20 DTDs and Schemas Because XML can be anything, it must be made into something. Rules for arranging and interpreting XML. DTD (Document Type Definition): Wide tool support, well-suited for documentation * DocBook DTD (1991): Traditional, bookbased, better suited to linear text and print * Darwin Information Typing Architecture (DITA) DTD (2005): New, topic-based, better suited to modular text, web, online help Schemas: New, more powerful, from the database world, wave of the future

21 Example: DocFrame DTD by Scriptorium, Inc. (based on Docbook)

22 New on the DTD Scene: DITA IBM published DITA in Donated to OASIS in 2004 (Organization for the Advancement of Structured Information Standard). Made OASIS standard, IBM, Nokia, Adobe, Autodesk fully DITA. Topic-based DTD based on topic maps, XML. Built on inheritance and specialization. Specialize from core information types to define unique content without losing architectural integrity.

23 New on the DTD Scene: DITA Information typing applies a template or pattern to a specific kind of information. A DITA topic is the basic unit of authoring and reuse with three base types. Concept: What goals to accomplish. Task: How to accomplish goals. Reference: Factual information needed.

24 New on the DTD Scene: DITA Not governed by media-specific constructs such as book chapters, paragraphs, and lists. A book turned into web pages reads like a book with obvious limitations in new medium. Topics and tasks instead. 47 base elements, e.g., task: prereq, steps, result. 12 map elements, 6 link elements (xref, link), assorted others, for total of 155 predefined elements. DITA maps collect/organize references to DITA topics to indicate the relationships among the topics. Build manifests for DITA projects, or TOC for deliverables.

25 International DITA Conference March 23-25, 2006 NCSU McKimmon Center in Raleigh Currently, RTP is the DITA Mecca.

26 DITA in Altova Authentic (XMLspy)

27 DITA in Syntext Serna (Win, Mac, Linux)

28 XML Editors that Support DITA Altova Authentic, free (Win) Syntext Serna, $45 (Win, Mac Linux) Adobe Framemaker 7.2, $500 (Win, Solaris) Altova XMLspy, $ (Win) BlastRadius XMetaL Author, DITA Edition, $ (Win) Arbortext Epic Editor, $860 (Win, Solaris) AuthorIT, $ (Win) ContentMapper (Win, on top of Word)

29 Output: CSS, XSL and XSLT XML + CSS (Cascading Style Sheet) displays XML in a browser without transforms (linked, embedded, inline). XSL (Extensible Stylesheet Language) describes how XML files are formatted. XSLT (+Transform) transforms or converts XML into other formats. Single-sources to different formats.

30 Print and PDF XSL-FO (XSL Formatting Objects). Specifies visual formatting of XML. Used to get XML into print and PDF. Not mature or easy. Adobe Framemaker, Acrobat, distiller, print server generally used to produce print and PDF from XML. XML is brought in to build print docs as a last stage rather than first. Content creation/maintenance happens in XML. Print docs are an output after custom improvements are made for the medium.

31 Storage and Management XML fits in a lot of places. Flat files. Reports of topics handled fine by DITA. Databases Hybrid FF and DB Content Management Systems Feed the portal Push the content

32 IT Alchemy: The Cucumber (Base) Structured authoring XML XML editors, apps that roundtrip XML DTD or Schema Output tools: CSS, XSL, XSLT Print and PDF engine File system, database, and/or CMS

33 The tools exist in open toolkits, using open standards, with sound exchange processes. What s the miracle?

34 People and Processes Not easy to do even with people convinced and workflow in place. Legacy content. New content written one word at a time. Upfront analysis and planning. Keep it simple. Cooperation on methods and goals. Adopt and consistently apply standards. Make it possible for people to contribute with their preferred tools, if possible. Mindset change to move from free-form, page-based writing to structure. Like moving from longhand to word processing.

35 What are you doing? And how? IT documentation Help systems Content development and management Digital and intellectual assets Repositories Portals Databases

36 Links

MadCap Flare Training

MadCap Flare Training Course Overview Welcome Audience Course Overview Preparing Your Computer for the Course Flare Overview What Is Flare? Getting Around in Flare User Interface Ribbon or Toolbars Projects