Advanced Technical Writing 2006

1
Advanced Technical Writing2006
Session 3
2
Today in Class

• Teams pitch poster concepts
• Meet with your editorial team, show us how your
  material fits with the whole concept
• Brief intro to XML
• Basics of Topic-Based Authoring

3
A brief introduction to XML
As customized as necessary As generalized as
possible
4
What is XML

• eXtensible Markup Language (much cooler than eML,
  eh?)
• Think of it as a generic way to describe markup
  languagesallowing users to create their own tags
  which describe what is sometimes called the
  semantic structure of a document

5
What is XML

• Still confused? XML is a subset of SGML, the
  publishing industry standard for describing
  content so that it can be stored, referenced,
  distributed, and presented consistently across
  diverse systems

6
This is XML
This could be finer grained..

• lt?xml version"1.0"?gt
• ltcitationgt
• ltauthorgtHart-Davidson, Williamlt/authorgt
• ltdategt2000lt/dategt
• ltpublishergt
• ltpnamegtDrybooks Inc.lt/pnamegt
• ltpcitygtAntwerplt/pcitygt
• lt/publishergt
• lt/citationgt

Well formed, but not valid XML
7
What does XML do? 1

• XML allows you to define the pieces of
  information (or objects, as we came to know them
  last week) that make up a document in such a way
  as to allow both humans and machines to recognize
  them and act upon them

8
What does XML do? 2

• For machines, XML defines the logical structure
  of the document, giving names to things so they
  can be recognized (parsed) or referenced in
  conditional statements, etc
• for people, it provides a way to describe what
  Id rather call the rhetorical structure of the
  document

9
How does XML work?
xml
style rules
Dtd
An xml document is made valid when a Document
Type Definition (or Schema) is present that
describes types of elements and the relationships
among elements for the document
10
An XML scenario, 1
DITA
This involves recreating the manual as a set of
topics...each is stored as an XML file
Bill is transforming a set of training materials,
shipped as PDF files on a CD, for publication on
the web
11
An XML scenario, 1
The XSLT transforms XML into HTML CSS for
display in a browser
Bill then creates an XSLT document that describes
how the web-based version should look
Manual Style Rules
He will later create a separate XSLT for the PDF
versions
12
An XML scenario, cont.
Bill doesnt worry, using the new DTD, all he has
to do is create a new set of style rules.
Bills editor wants the files in a printable
format
13
Topic-Based Authoring withDITA a preview
Topic - the highest level semantic unit, a topic
can be of any length documents are made up of
topics (one or many) Task - one subtype of
topic, a how to Concept - another subtype of
topic, a what is Map - a list of references to
other topics and those topics sub-structures
used to create a particular document or view
14
A bit more about DTDs

• DTDs are the place where XML tag sets are
  defined. They are pretty powerful meta-documents
  that determine what the folks reading and writing
  XML documents of a particular type can and cannot
  include, search for, etc.
• DITA is defined in a DTD (as well as the more
  muscular cousin of the DTD, a Schema)

15
A bit more about DTDs

• We can consider DTDs, or their newer and more
  flexible counterparts called XML Schema, as
  workspaces. They define conceptual and physical
  boundaries for content developers
• Their design is a critical task for the content
  specialist. Well wrought DTDs Schema can
  greatly impact the both user experience, the
  development cycle, and, hence, the
  business/mission.

16
A DITA workspace roles

• The following slide lists roles that team members
  might play in a content-production situation
  where DITA is in use.
• Read more here
• http//www.winwriters.com/articles/DITA/

17
Type architect - Analyzes topic types needed to
accommodate content being produced, and defines
new topic types if needed. Topic writer - Writes
and edits topics, according to the topic-type
standards established for the project by the XML
architect. Information architect - Analyzes the
overall structure of the content, groups it into
topic collections, and defines maps that describe
the relationship of topics to each other. Build
developer - Processes the DITA source topics into
various formats, as needed for product
deliverables. Information designer -
Establishes the "look and feel" of the output
presentation.
18
Lets Do a Little XML exercise

• Think about the poster we are making. Come up
  with some XML tags to describe the semantic
  structure of the poster
• Draft a list of tags that correspond to your
  topic
• Name your tags with semantic labels that is,
  identify functional objects within the document

19
Inside the DTD

• A DTD is just a list of declarations. Lets
  consider three common types
• The first declaration names the DOCTYPE.

lt!DOCTYPE document_name the rest of the dtd
heregt
20
Inside the DTD, 2

• 2. Then come declarations of document ELEMENTs.

lt!ELEMENT element_name (data_type)gt
21
Inside the DTD, 3

• 3. Finally, there may be declarations for
  ATTRIBUTES of an ELEMENT.

lt!ATTLIST parent_element attribute_name data_type
default_valuegt
22
This is a DTD

• lt!DOCTYPE citation
• lt!ELEMENT book (author, date, publisher)gt
• lt!ELEMENT author (PCDATA)gt
• lt!ELEMENT date (PCDATA)gt
• lt!ELEMENT publisher (PCDATA)gt
• lt!ATTLIST publisher pname CDATA REQUIREDgt
• lt!ATTLIST publisher pcity CDATA REQUIREDgt
• gt

23
A Few More Xs

• What is XHTML?
• Quite simply, it is html redescribed as an XML
  DTD. Or another way to say it is that XHTML is
  the current default web DTD.

24
A Few More Xs

• What is XSL? XSL-T?
• The xml stylesheet specification. XSLT is a very
  robust spec for transforming an XML document of
  one type into one of another typemeaning you can
  do more than just style information for
  display, you can also change it into other forms.

25
Good references for CSS XML

• www.webmonkey.com
• www.xml.com
• www.w3c.org

26
Helpful Readings

• http//12.108.175.91/ebookweb/stories/storyReader
  380
• An article on eBookWeb about XML, structure, and
  content.
• If you have it handy, you can read Rockley Ch. 14
  and Ch. 20.

27
Next Time

• Semantic Markup 1 - DITA, a chance to see XML in
  use in the TC world
• Individuals Begin authoring the digital assets
  for your part of the poster
• Teams Work on the semantic structure of your
  topic area