Advanced technical writing 2006
1 / 27

Advanced Technical Writing 2006 - PowerPoint PPT Presentation

  • Uploaded on

Advanced Technical Writing 2006. Session #3. 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. A brief introduction to XML. As customized as necessary &

I am the owner, or an agent authorized to act on behalf of the owner, of the copyrighted work described.
Download Presentation

PowerPoint Slideshow about ' Advanced Technical Writing 2006' - annot

An Image/Link below is provided (as is) to download presentation

Download Policy: Content on the Website is provided to you AS IS for your information and personal use and may not be sold / licensed / shared on other websites without getting consent from its author.While downloading, if for some reason you are not able to download a presentation, the publisher may have deleted the file from their server.

- - - - - - - - - - - - - - - - - - - - - - - - - - E N D - - - - - - - - - - - - - - - - - - - - - - - - - -
Presentation Transcript

Today in class
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

A brief introduction to xml
A brief introduction to XML

As customized as necessary


As generalized as possible

What is xml
What is XML

  • eXtensible Markup Language (much cooler than eML, eh?)

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

What is xml1
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

This is xml
This is XML*

This could

be finer


<?xml version="1.0"?>


<author>Hart-Davidson, William</author>



<pname>Drybooks Inc.</pname>




* Well formed, but not valid XML…

What does xml do 1
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

What does xml do 2
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 I’d rather call the rhetorical structure of the document

How does xml work
How does XML work?





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 1
An XML scenario, 1


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

An xml scenario 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…

An xml scenario cont
An XML scenario, 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 with dita a preview
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;”

  • A bit more about dtds
    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)

    A bit more about dtds1
    A bit more about DTDs

    We can consider DTD’s, 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 DTD’s & Schema can greatly impact the both user experience, the development cycle, and, hence, the business/mission.

    A dita workspace roles
    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:

    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 exercise
    Let’s 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

    Inside the dtd
    Inside the DTD…

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

    • The first declaration names the DOCTYPE.

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

    Inside the dtd 2
    Inside the DTD, 2

    2. Then come declarations of document ELEMENTs.

    <!ELEMENT element_name (#data_type)>

    Inside the dtd 3
    Inside the DTD, 3

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

    <!ATTLIST parent_element attribute_name data_type #default_value>

    This is a dtd
    This is a DTD

    <!DOCTYPE citation

    [<!ELEMENT book (author, date, publisher)>

    <!ELEMENT author (#PCDATA)>

    <!ELEMENT date (#PCDATA)>

    <!ELEMENT publisher (#PCDATA)>

    <!ATTLIST publisher pname CDATA #REQUIRED>

    <!ATTLIST publisher pcity CDATA #REQUIRED>



    A few more x s
    A Few More X’s…

    • 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.

    A few more x s1
    A Few More X’s…

    • 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 type…meaning you can do more than just “style” information for display, you can also change it into other forms.

    Good references for css xml
    Good references for CSS & XML

    Helpful readings
    Helpful Readings


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

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

    Next time
    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