advanced technical writing 2006

Advanced Advanced Technical Technical WritingWriting

20062006

Session #3

Today in Class…Today in Class…

►Teams pitch poster concepts:Teams pitch poster concepts: Meet with your editorial team, Meet with your editorial team, show us how your material fits show us how your material fits with the whole conceptwith the whole concept

►Brief intro to XMLBrief intro to XML►Basics of Topic-Based Basics of Topic-Based AuthoringAuthoring

A brief introduction to A brief introduction to XMLXML

As customized as necessary

&

As generalized as possible

What is XMLWhat is XML

►eeXXtensible tensible MMarkup arkup LLanguage anguage ((muchmuch cooler than eML, eh?)cooler than eML, eh?)

►Think of it as a generic way to Think of it as a generic way to describe markup languages…describe markup languages…allowing users to create their allowing users to create their own tags which describe what is own tags which describe what is sometimes called the “semantic sometimes called the “semantic structure” of a documentstructure” of a document

What is XMLWhat is XML

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

This is XML*This is XML*

<?xml version="1.0"?><?xml version="1.0"?><citation><citation><author>Hart-Davidson, William</author><author>Hart-Davidson, William</author><date>2000</date><date>2000</date><publisher><publisher>

<pname>Drybooks Inc.</pname><pname>Drybooks Inc.</pname><pcity>Antwerp</pcity><pcity>Antwerp</pcity>

</publisher></publisher></citation></citation>

* Well formed, but not valid XML…

This couldbe finergrained..

What does XML do? 1What does XML do? 1

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

What does XML do? 2What does XML do? 2

For machines, XML defines the For machines, XML defines the logical structure of the logical structure of the document, giving names to things document, giving names to things so they can be recognized so they can be recognized (parsed) or referenced in (parsed) or referenced in conditional statements, etcconditional statements, etc

……for people, it provides a way to for people, it provides a way to describe what I’d rather call the describe what I’d rather call the rhetorical structure of the rhetorical structure of the documentdocument

How does XML work?How does XML work?

xml

Dtd

stylerules

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

An XML scenario, 1An XML scenario, 1

Bill is transforming a set of training materials, shipped as PDF files on a CD, for publication on the web

DITA

This involves recreating the manual as a set of “topics”...each is stored as an XML file

An XML scenario, 1An XML scenario, 1

Bill then creates an XSLT document that describes how the web-based version should look

Manual Style Rules

The XSLT transforms XML into HTML + CSS for display in a browserHe will later create a

separate XSLT for the PDF versions…

An XML scenario, An XML scenario, cont. cont.

Bill doesn’t worry, using the new DTD, all he has to do is create a new set of style rules.

Bill’s editor wants the files in a printable format…

Topic-Based Authoring Topic-Based Authoring withwith

DITA: a previewDITA: a previewTopic - 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;”

A bit more about DTDsA bit more about DTDs

DTDs are the place where XML tag sets DTDs are the place where XML tag sets are defined. They are pretty are defined. They are pretty powerful meta-documents that powerful meta-documents that determine what the folks reading and determine what the folks reading and writing XML documents of a writing XML documents of a particular type can and cannot particular type can and cannot include, search for, etc.include, search for, etc.

DITA is defined in a DTD (as well as DITA is defined in a DTD (as well as the more muscular cousin of the DTD, the more muscular cousin of the DTD, a Schema)a Schema)

A bit more about DTDsA bit more about DTDs

We can consider DTD’s, or their newer We can consider DTD’s, or their newer and more flexible counterparts called and more flexible counterparts called XML Schema, as workspaces. They XML Schema, as workspaces. They define conceptual and physical define conceptual and physical boundaries for content developersboundaries for content developers

Their design is a critical task for the Their design is a critical task for the content specialist. Well wrought content specialist. Well wrought DTD’s & Schema can greatly impact the DTD’s & Schema can greatly impact the both user experience, the development both user experience, the development cycle, and, hence, the cycle, and, hence, the business/mission.business/mission.

A DITA “workspace”: A DITA “workspace”: rolesroles

The following slide lists roles that The following slide lists roles that team members might play in a team members might play in a content-production situation where content-production situation where DITA is in use.DITA is in use.

Read more here:Read more here:

http://www.winwriters.com/http://www.winwriters.com/articles/DITA/articles/DITA/

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.

Let’s Do a Little XML Let’s Do a Little XML exerciseexercise

Think about the poster we are making. Think about the poster we are making. Come up with some XML tags to Come up with some XML tags to describe the semantic structure of describe the semantic structure of the posterthe poster

► Draft a list of tags that correspond Draft a list of tags that correspond to your “topic”to your “topic”

► Name your tags with semantic labels… Name your tags with semantic labels… that is, identify functional objects that is, identify functional objects within the documentwithin the document

Inside the DTD…Inside the DTD…

A DTD is just a list of declarations. Let’s A DTD is just a list of declarations. Let’s consider three common types :consider three common types :

1.1. The first declaration names the DOCTYPE.The first declaration names the DOCTYPE.

<!DOCTYPE document_name […the rest of the dtd here]>

Inside the DTD, 2Inside the DTD, 2

2. Then come declarations of 2. Then come declarations of document ELEMENTs. document ELEMENTs.

<!ELEMENT element_name (#data_type)>

Inside the DTD, 3Inside the DTD, 3

3. Finally, there may be 3. Finally, there may be declarations for ATTRIBUTES of declarations for ATTRIBUTES of an ELEMENT.an ELEMENT.<!ATTLIST parent_element attribute_name data_type #default_value>

This is a DTDThis is a DTD

<!DOCTYPE citation <!DOCTYPE citation [<!ELEMENT book (author, date, publisher)>[<!ELEMENT book (author, date, publisher)><!ELEMENT author (#PCDATA)><!ELEMENT author (#PCDATA)><!ELEMENT date (#PCDATA)><!ELEMENT date (#PCDATA)><!ELEMENT publisher (#PCDATA)><!ELEMENT publisher (#PCDATA)><!ATTLIST publisher pname CDATA #REQUIRED><!ATTLIST publisher pname CDATA #REQUIRED><!ATTLIST publisher pcity CDATA #REQUIRED><!ATTLIST publisher pcity CDATA #REQUIRED>

]]>>

A Few More X’s…A Few More X’s…

► What is XHTML?What is XHTML?

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

A Few More X’s…A Few More X’s…

► What is XSL? XSL-T?What is XSL? XSL-T?

The xml stylesheet specification. XSLT The xml stylesheet specification. XSLT is a very robust spec for transforming is a very robust spec for transforming an XML document of one type into one of an XML document of one type into one of another type…meaning you can do more another type…meaning you can do more than just “style” information for than just “style” information for display, you can also change it into display, you can also change it into other forms.other forms.

Good references for Good references for CSS & XMLCSS & XML

www.webmonkey.comwww.webmonkey.com

www.xml.comwww.xml.com

www.w3c.orgwww.w3c.org

Helpful ReadingsHelpful Readings

► http://12.108.175.91/ebookweb/stohttp://12.108.175.91/ebookweb/stories/storyReader$380ries/storyReader$380

An article on eBookWeb about XML, An article on eBookWeb about XML, structure, and content. structure, and content.

If you have it handy, you can read If you have it handy, you can read Rockley Ch. 14 and Ch. 20. Rockley Ch. 14 and Ch. 20.

Next Time…Next Time…

►Semantic Markup 1 - DITA, a Semantic Markup 1 - DITA, a chance to see XML in use in chance to see XML in use in the TC worldthe TC world

►Individuals: Begin authoring Individuals: Begin authoring the digital assets for your the digital assets for your part of the posterpart of the poster

►Teams: Work on the semantic Teams: Work on the semantic structure of your topic areastructure of your topic area