Technical Writing 2013 Unit #2. This week… ► Individuals complete Ethics Statement. ► Discussion of TC characteristics ► Brief intro to XML ► Basics of.

Technical Technical WritingWriting

20132013

Unit #2

This week…This week…

►Individuals complete Ethics Individuals complete Ethics Statement.Statement.

►Discussion of TC characteristicsDiscussion of TC characteristics►Brief intro to XMLBrief intro to XML►Basics of Communication Basics of Communication

ModelingModeling

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 own allowing users to create their own tags which describe what is tags which describe what is sometimes called the sometimes called the ““semantic semantic structurestructure”” of a document of a document

What is XMLWhat is XML

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

This is XML*This is XML*

<?xml version="1.0"?><?xml version="1.0"?><citation><citation>

<author>Balzotti, Jon</author><author>Balzotti, Jon</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 to a document in such a way as to allow both humans and 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 document, logical structure of the document, giving names to things so they can giving names to things so they can be recognized (parsed) or be recognized (parsed) or referenced in conditional referenced in conditional statements, etcstatements, etc

……for people, it provides a way to for people, it provides a way to describe what Idescribe what I’’d call the d 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

Jon 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

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

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

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

Topic-Based Authoring Topic-Based Authoring withwith

DITA: a previewDITA: a previewTopicTopic - the highest level semantic unit, - the highest level semantic unit, a topic can be of any length; a topic can be of any length; documents are made up of topics (one documents are made up of topics (one or many)or many)

TaskTask - one subtype of topic, a - one subtype of topic, a ““how how toto””

ConceptConcept - another subtype of - another subtype of topic, a topic, a ““what iswhat is””

MapMap - a list of references to other - a list of references to other topics and those topicstopics and those topics’’ sub-structures sub-structures used to create a particular document used to create a particular document or or ““viewview””

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 powerful are defined. They are pretty powerful meta-documents that determine what meta-documents that determine what the folks reading and writing XML the folks reading and writing XML documents of a particular type can documents of a particular type can and cannot include, search for, etc.and cannot include, search for, etc.

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

A bit more about DTDsA bit more about DTDs

We can consider DTDs, or their newer We can consider DTDs, 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 DTDs content specialist. Well wrought DTDs & Schema can greatly impact the both & Schema can greatly impact the both user experience, the development user experience, the development cycle, and, hence, the cycle, and, hence, the business/mission.business/mission.

A DITA A DITA ““workspaceworkspace””: roles: roles

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

Read more here:Read more here:

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

Type architect Type architect - Analyzes topic types needed to - Analyzes topic types needed to accommodate content being produced, and accommodate content being produced, and defines new topic types if needed.defines new topic types if needed.

Topic writer Topic writer - Writes and edits topics, according to - Writes and edits topics, according to the topic-type standards established for the the topic-type standards established for the project by the XML architect.project by the XML architect.

Information architect Information architect - Analyzes the overall - Analyzes the overall structure of the content, groups it into topic structure of the content, groups it into topic collections, and defines maps that describe the collections, and defines maps that describe the relationship of topics to each other.relationship of topics to each other.

Build developer Build developer - Processes the DITA source topics - Processes the DITA source topics into various formats, as needed for product into various formats, as needed for product deliverables.deliverables.

Information designer Information designer - Establishes the "look and - Establishes the "look and feel" of the output presentation.feel" of the output presentation.

LetLet’’s Do a Little XML s Do a Little XML exerciseexercise

Think about a personal web page you Think about a personal web page you would like to make. Come up with some would like to make. Come up with some XML tags to describe the semantic XML tags to describe the semantic structure of the personal pagestructure of the personal page

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

► 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. LetA DTD is just a list of declarations. Let’’s s consider three common types :consider three common types :

1.1. The first declaration names the The first declaration names the DOCTYPE. DOCTYPE. <!DOCTYPE document_name […the <!DOCTYPE document_name […the rest of the dtd here]>rest of the dtd here]><!DOCTYPE document_name […the <!DOCTYPE document_name […the rest of the dtd here]>rest of the dtd here]>

Inside the DTD, 2Inside the DTD, 2

2.2. Then come declarations of document Then come declarations of document ELEMENTs. ELEMENTs.

<!ELEMENT element_name (#data_type)><!ELEMENT element_name (#data_type)>

Inside the DTD, 3Inside the DTD, 3

3.3. Finally, there may be Finally, there may be declarations for declarations for ATTRIBUTESATTRIBUTES of an of an ELEMENT.ELEMENT.<!ATTLIST parent_element <!ATTLIST parent_element attribute_name data_type attribute_name data_type #default_value>#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 <!ATTLIST publisher pname CDATA #REQUIRED>#REQUIRED><!ATTLIST publisher pcity CDATA #REQUIRED><!ATTLIST publisher pcity CDATA #REQUIRED>

]]>>

A Few More Xs…A Few More Xs…

► What is XHTML?What is XHTML?

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

A Few More Xs…A Few More Xs…

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

The XML stylesheet specification. The XML stylesheet specification. XSLT is a very robust spec for XSLT is a very robust spec for transforming an XML document of transforming an XML document of one type into one of another type…one type into one of another type…meaning you can do more than just meaning you can do more than just ““stylestyle”” information for display, you information for display, you can also change it into other forms.can also change it into 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/http://12.108.175.91/ebookweb/stories/storyReader$380stories/storyReader$380

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

Integrating Visual Integrating Visual ElementsElements

►““A picture is worth a thousand A picture is worth a thousand words.” Presentation is as words.” Presentation is as important as content and should important as content and should be a priority for your technical be a priority for your technical documents.documents.

►The use of images, diagrams, The use of images, diagrams, charts, and other visual elements charts, and other visual elements will be an important part of your will be an important part of your semesters. semesters.

StructureStructure

►Concision, concision, concision. Concision, concision, concision. Technical communication gets Technical communication gets right to the point and avoids right to the point and avoids lengthy introductions and lengthy introductions and conclusions. conclusions.

►Don’t use a paragraph to say what Don’t use a paragraph to say what you can with one sentence.you can with one sentence.

TimelinessTimeliness

►Technical communication has an Technical communication has an expiration date. Meaning, the expiration date. Meaning, the information you prepare today may be information you prepare today may be outdated next year.outdated next year.

►Question to consider: Will information Question to consider: Will information need to be updated on a regular need to be updated on a regular basis, if so how often? TC should use basis, if so how often? TC should use a strategy to remain timely with a strategy to remain timely with information they produce.information they produce.

Ethical CommunicationEthical Communication

►Sometimes, you will need to Sometimes, you will need to communicate legal rights and duties communicate legal rights and duties as they relate to your subject. Every as they relate to your subject. Every attempt should be made to eliminate attempt should be made to eliminate ambiguous or confusing legal jargon. ambiguous or confusing legal jargon.

►Confidentiality ensures frankness Confidentiality ensures frankness from sources regarding primary from sources regarding primary information obtained through information obtained through surveys etc. surveys etc.

Cultural PreferencesCultural Preferences

►Analysis should provide Analysis should provide information on the audience and information on the audience and direction on how to adapt to an direction on how to adapt to an array of cultural preferences.array of cultural preferences.

►Humor, personal space, and eye Humor, personal space, and eye contact may appear to apply to TC contact may appear to apply to TC only minimally, but small mistakes only minimally, but small mistakes can lead to drastic consequences. can lead to drastic consequences.

What is Communication What is Communication ModelingModeling

►Used to explain the way people Used to explain the way people exchange informationexchange information

►Think of it as a way to describe or Think of it as a way to describe or illustrate communication more illustrate communication more broadly…allowing TC writers to broadly…allowing TC writers to determine the best approach for determine the best approach for each project.each project.

Simple Transaction ModelSimple Transaction Model

Ted interprets the message and provides feedback to Jon. Jon processes the feedback and modifies the message.

Jon (sender) wants to send a message to Ted (receiver).

Interference Transaction Interference Transaction ModelModel

► Builds upon the simple transaction model Builds upon the simple transaction model by adding the concept of by adding the concept of interferenceinterference, , both internal and external. both internal and external. External interference External interference is the surrounding is the surrounding

noise and distraction that serves as noise and distraction that serves as obstacles to communication (ex. a crying obstacles to communication (ex. a crying baby). baby).

Internal interference Internal interference may be subjective, may be subjective, a person’s inability to concentrate a person’s inability to concentrate because of mental fatigue, or the because of mental fatigue, or the inability to remain objective towards the inability to remain objective towards the topic.topic.

Interference Transaction Interference Transaction ModelModel

Ted receives the message and then decodes message and provides feedback.

Jon (sender) wants to send a message to Ted (receiver) but can’t. Jon encodes the message by determining structure and content.

Interference

CMAPP Communication CMAPP Communication ModelModel

►CMAPP (Context, Message, CMAPP (Context, Message, Audience, Purpose, and Product) Audience, Purpose, and Product) applies to technical applies to technical communication that omit the communication that omit the sender, receiver, and transmission sender, receiver, and transmission elements.elements.

CMAPP Communication CMAPP Communication ModelModel

The product refers to the technical document. Each element impacts and affects the others continuously.

The message effects the audience to which the communication is directed. The purpose affects the intent of the message.

Message Audience

ProductPurpose