Transcript Unit Two-Overview/Study Guide PPT

Review for Unit #2 Quiz
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
► eXtensible
Markup Language
► 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>McCool, Lynn</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) 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 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 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 constructed DTDs & Schema can greatly impact
the user experience, the development cycle, and in
turn, 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 topictype 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. Next, the 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 rewritten 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?
 It is 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.
If you’re interested in learning more...
► Good
references for CSS & XML
 www.webmonkey.com
 www.xml.com
 www.w3c.org
Additional 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 the projects you submit this
semester.
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
date.
communication has an expiration
►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?
► It
is 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.