1. Technical Writing 2013 Unit #2

2. This week… ► Individuals complete Ethics Statement. ► Discussion of TC characteristics ► Brief intro to XML ► Basics of Communication Modeling

3. A brief introduction to XML As customized as necessary & As generalized as possible

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

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

6. This is XML* <citation> Balzotti, Jon Balzotti, Jon <date>2000</date><publisher> Drybooks Inc. Drybooks Inc. <pcity>Antwerp</pcity></publisher></citation> * Well formed, but not valid XML… This could be finer grained..

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

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

9. How does XML work? xml Dtd style rules 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

10. An 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

11. An 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 browser He will later create a separate XSLT for the PDF versions…

12. An XML scenario, 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…

13. 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”

14. 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)

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

16. 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/

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

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

19. Inside the DTD… A DTD is just a list of declarations. Let ’ s consider three common types : 1.The first declaration names the DOCTYPE.

20. Inside the DTD, 2 2.Then come declarations of document ELEMENTs.

21. Inside the DTD, 3 3.Finally, there may be declarations for ATTRIBUTES of an ELEMENT.

22. This is a DTD <!DOCTYPE citation [ [ ]>

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

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

25. Good references for CSS & XML ► www.webmonkey.com www.webmonkey.com ► www.xml.com www.xml.com ► www.w3c.org www.w3c.org

26. Helpful Readings ► http://12.108.175.91/ebookweb/stories/s toryReader$380 http://12.108.175.91/ebookweb/stories/s toryReader$380 http://12.108.175.91/ebookweb/stories/s toryReader$380 An article on eBookWeb about XML, structure, and content.

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

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

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

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

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

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

33. Simple 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).

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

35. Interference Transaction Model 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

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

37. CMAPP Communication Model 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