Technical Writing 2013

1. Technical Writing2013 Review for Unit #2 Quiz

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

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* This could be finer grained.. <?xml version="1.0"?> <citation> <author>McCool, Lynn</author> <date>2000</date> <publisher> <pname>Drybooks Inc.</pname> <pcity>Antwerp</pcity> </publisher> </citation> * Well formed, but not valid XML…

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

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

10. An XML scenario, 1 DITA This involves recreating the manual as a set of “topics”...each is stored as an XML file Jon is transforming a set of training materials, shipped as PDF files on a CD, for publication on the web

11. An XML scenario, 1 The XSLT transforms XML into HTML + CSS for display in a browser Jon 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…

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

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 constructed DTDs & Schema can greatly impact the userexperience, the developmentcycle, and in turn, 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 : • The first declaration names the DOCTYPE. • <!DOCTYPE document_name […the rest of the dtd here]>

20. Inside the DTD, 2 • Next, the declarations of document ELEMENTs. <!ELEMENT element_name (#data_type)>

21. Inside the DTD, 3 • Finally, there may be declarations for ATTRIBUTES of an ELEMENT. <!ATTLIST parent_element attribute_name data_type #default_value>

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

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

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

25. If you’re interested in learning more... • Good references for CSS & XML • www.webmonkey.com • www.xml.com • www.w3c.org

26. Additional Readings • http://12.108.175.91/ebookweb/stories/storyReader$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 visualelements will be an important part of the projects you submit this semester.

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

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

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