Transcript Unit Two overview

Unit #2
Technical
Writing
2013
This week…
► Individuals
complete Ethics
Statement.
► Discussion of TC characteristics
► Brief intro to XML
► Basics of Communication Modeling
A brief introduction to XML
As customized as
necessary
&
As generalized as
possible
What is XML
Markup Language (much
cooler than eML, eh?)
► eXtensible
► 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 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*
<?xml version="1.0"?>
<citation>
<author>Balzotti, Jon</author>
<date>2000</date>
<publisher>
<pname>Drybooks Inc.</pname>
<pcity>Antwerp</pcity>
</publisher>
</citation>
This could
be finer
grained..
* Well formed, but not valid
XML…
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
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 call the
rhetorical structure of the
document
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
An XML scenario, 1
DITA
Jon is transforming a
set of training
materials, shipped as
PDF files on a CD, for
publication on the web
This involves
recreating the
manual as a set of
“topics”...each is
stored as an XML file
An XML scenario, 1
The XSLT
transforms
Jon then creates
XML into
Manual
an XSLT document
Style
HTML
+
Rules
that describes how
CSS for
the web-based
display in
version should
look
He will later create a a browser
separate XSLT for
the PDF versions…
An XML scenario, cont.
Jon’s editor wants the
files in a printable
format…
Jon doesn’t worry,
using the new DTD, all
he has to do is create a
new set of style rules.
Topic-Based Authoring with
DITA: 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
DTDs are the place where XML tag sets are
defined. They are pretty powerful metadocuments 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 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.
A DITA “workspace”: roles
The next 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/
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
Think about a personal web page you would
like to make. Come up with some XML tags
to describe the semantic structure of the
personal page
► 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…
A DTD is just a list of declarations. Let’s
consider three common types :
1. The first declaration names the DOCTYPE.
<!DOCTYPE document_name […the rest of
the dtd here]>
Inside the DTD, 2
2. Then come declarations of document
ELEMENTs.
<!ELEMENT element_name (#data_type)>
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
<!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 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.
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 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
► www.webmonkey.com
► www.xml.com
► www.w3c.org
Helpful Readings
► http://12.108.175.91/ebookweb/stories/s
toryReader$380
An article on eBookWeb about XML,
structure, and content.
Integrating Visual Elements
► “A
picture is worth a thousand words.”
Presentation is as important as
content and should be a priority for
your technical documents.
► The
use of images, diagrams, charts,
and other visual elements will be an
important part of your semesters.
Structure
► Concision,
concision, concision.
Technical communication gets right to
the point and avoids lengthy
introductions and conclusions.
► Don’t
use a paragraph to say what you
can with one sentence.
Timeliness
► Technical
communication has an
expiration date. Meaning, the
information you prepare today may be
outdated next year.
► Question
to consider: Will information
need to be updated on a regular basis,
if so how often? TC should use a
strategy to remain timely with
information they produce.
Ethical Communication
► Sometimes,
you will need to
communicate legal rights and duties as
they relate to your subject. Every
attempt should be made to eliminate
ambiguous or confusing legal jargon.
► Confidentiality
ensures frankness from
sources regarding primary information
obtained through surveys etc.
Cultural Preferences
► Analysis
should provide information on
the audience and direction on how to
adapt to an array of cultural
preferences.
► Humor,
personal space, and eye
contact may appear to apply to TC only
minimally, but small mistakes can lead
to drastic consequences.
What is Communication
Modeling
► Used
to explain the way people
exchange information
► Think
of it as a way to describe or
illustrate communication more
broadly…allowing TC writers to
determine the best approach for each
project.
Simple Transaction Model
Jon (sender) wants to
send a message to
Ted (receiver).
Ted interprets the
message and provides
feedback to Jon. Jon
processes the feedback
and modifies the
message.
Interference Transaction
Model
► Builds
upon the simple transaction model by
adding the concept of interference, both
internal and external.
 External interference is the surrounding
noise and distraction that serves as
obstacles to communication (ex. a crying
baby).
 Internal interference may be subjective, a
person’s inability to concentrate because
of mental fatigue, or the inability to
remain objective towards the topic.
Interference Transaction
Model
Interference
Jon (sender) wants to
send a message to Ted
(receiver) but can’t. Jon
encodes the message
by determining
structure and content.
Ted receives the
message and then
decodes message and
provides feedback.
CMAPP Communication
Model
► CMAPP
(Context, Message, Audience,
Purpose, and Product) applies to
technical communication that omit the
sender, receiver, and transmission
elements.
CMAPP Communication
Model
Message
Audience
Purpose
Product
The message effects
the audience to which
the communication is
directed. The purpose
affects the intent of
the message.
The product refers to
the technical
document. Each
element impacts and
affects the others
continuously.