Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

XML authoring simplified for one and all: Writers UA

277 views

Published on

10 tips to author content in DITA using Adobe FrameMaker 2015.

Published in: Education
  • Get Paid For Your Opinions! Earn $5-$10 cash on your first survey.  http://t.cn/AieX2Loq
       Reply 
    Are you sure you want to  Yes  No
    Your message goes here
  • Be the first to like this

XML authoring simplified for one and all: Writers UA

  1. 1. Bernard Aschwanden www.publishingsmarter.com bernard@publishingsmarter.com XML Authoring Simplified For One and All 15:11 1 @aschwanden4stc
  2. 2. Housekeeping 15:11@aschwanden4stc 2  Thanks to Adobe and Joe for setting up this event  In under 10 ideas (was slides, but I don’t want you to write) 1. Setup of FrameMaker and create a bit of sample content 2. Overview of DITA in a single slide 3. Intro to all core topic types and elements 4. Behind the scenes (attributes) 5. Map 6. Concept 7. Task 8. Reference 9. Publish 10. Update/Publish again!
  3. 3. Standard disclaimer 15:11@aschwanden4stc  In the interest of brevity I will make some blanket statements to keep it simple  It’s not all 100% “the truth”, but I’ll stay close  Purists may complain  And they are wrong!  (except when they are right)  This can be interactive  Raise a hand when asked 3
  4. 4. Many options exist, so let’s get onto the same page (so to speak) @aschwanden4stc 15:11 4 Setting up the software
  5. 5. 1. Let’s standardize things: Edit > Preferences 15:11@aschwanden4stc 5 1 2 3
  6. 6. Enable Simplified XML (more on that later) 15:11@aschwanden4stc 6 1 2 3
  7. 7. If needed, relaunch, then File > New > XML 15:11@aschwanden4stc 7 1 2 3
  8. 8. By default you see this (or similar) 15:11@aschwanden4stc 8
  9. 9. Change to a structured author mode 15:11@aschwanden4stc 9 1 2
  10. 10. Structure View: Hierarchy of content 15:11@aschwanden4stc 10
  11. 11. Element Catalog: Contextual list 15:11@aschwanden4stc 11
  12. 12. Setup of a custom workspace (one time) 15:11@aschwanden4stc 12 1 2
  13. 13. Collapse by double-clicking 15:11@aschwanden4stc 13 1
  14. 14. Save your own workspace 15:11@aschwanden4stc 14 1 2 3 4
  15. 15. Remove <related-links> 15:11@aschwanden4stc 15 1
  16. 16. Add a title 15:11@aschwanden4stc 16 1
  17. 17. Content in doc and in Structure View 15:11@aschwanden4stc 17
  18. 18. Inline: View > Element Boundaries (as Tags) 15:11@aschwanden4stc 18
  19. 19. Add content in tags, select/delete related- links 15:11@aschwanden4stc 19
  20. 20. View > Hide Element Boundaries 15:11@aschwanden4stc 20
  21. 21. Save the file (anywhere, but make a folder) 15:11@aschwanden4stc 21
  22. 22. 2. Purpose of DITA 15:11@aschwanden4stc 22  According to me: A formal, XML-based rule set for creating content  Many people in tech comm already work with it  DITA enables enhanced use of source content in a vendor independent way  At the same time, take advantage of work vendors have already done!
  23. 23. 2: Overview of DITA in a single slide 15:11@aschwanden4stc 23  Darwin Information Typing Architecture  DITA is about Topic, Maps, Specializations  Some specializations include  concept, reference, task, glossary (topic based)  bookmap (map based)  domains (software, programming)  DITA 1.2 and 1.3 introduce more based on the standard core topics DITA Information Types Topic–Concept–Task–Reference
  24. 24. 3. Intro to core topic types and elements 15:11@aschwanden4stc 24 Maps and bookmaps • Used to plan, organize, and publish Reltables • Build relationships between topics in maps for enhanced links Topics • Types of info in maps generally a task, concept, or reference Specializations • Customize if other options are exhausted: not using this today
  25. 25. 4. Behind the scenes are attributes 15:11@aschwanden4stc 25 Maps and bookmaps • Used to plan, organize, and publish Reltables • Build relationships between info in maps Topics • Types of info in maps generally a task, concept, or reference Specializations • Customize as needed if other options are exhausted Attributes
  26. 26. 4b. You likely already know about attributes 15:11@aschwanden4stc 26  Think about HTML  <img src=“file.ext” height=“100” width=“200”>  <a href="http://www.publishingsmarter.com">Think DITA!</a>  In DITA it’s the same idea  <note type=“tip”>Kids: Listen to your teacher; it’s worth it!</note>  <p audience=“novice”> or <p audience=“expert”>  <p product=“Widget-o-matic”> or <p product=“Foo-blah- bulator”>  <cmd>Use the <ph platform=“win”>Explorer</ph> <ph platform=“mac”>Finder</ph> to organize your files.</cmd>
  27. 27. 5. Use maps to organize info 15:11@aschwanden4stc 27  Maps organize topics; they are a bit like a master document, book document, TOC, and site map  They use <topicref> in a specific order to organize info  At publish time the order drives some functions (i.e. TOC, related parent/child links)  Making a map is easy  At a high level, decide on primary goal  Make that goal clear  Add supporting content
  28. 28. 5. Let’s build a New <map> in FrameMaker 15:11@aschwanden4stc 281 2
  29. 29. File > Save Ditamap As... (m_DITA_and_FrameMaker) 15:11@aschwanden4stc 29
  30. 30. Different views based on preferences/functions 15:11@aschwanden4stc 30
  31. 31. Change text? Double click snippets to select all 15:11@aschwanden4stc 31
  32. 32. When content is selected, just type to edit 15:11@aschwanden4stc 32
  33. 33. Let’s add the concept to the book 15:11@aschwanden4stc 33
  34. 34. Add a <topicref> (a topic reference) 15:11@aschwanden4stc 34
  35. 35. Double-click a file that already exists 15:11@aschwanden4stc 35 1 2
  36. 36. So far, pretty simple, but a bit unimpressive 15:11@aschwanden4stc 36
  37. 37. 6. Concept explains ideas 15:11@aschwanden4stc  If people are wondering why they should do something, or the benefits, then a concept is likely needed  Answers the question what is or why by detailing information about something  Initial information that users must know before they can successfully work  Supports the task by providing an explanation that is outside the scope of the task 37
  38. 38. Key elements when getting started 15:11@aschwanden4stc 38  Before starting—common elements I like:  title is often a heading for the topic, (also used by sections, examples, figures, tables)  shortdesc is an initial brief statement in a topic that does NOT repeat the title, it enhances it  prolog is metadata or information about a topic that likely won’t see it’s way into print, but helps manage content. Title samples
  39. 39. Ours has those elements, and it’s in the map! 15:11@aschwanden4stc 39
  40. 40. Elements used in most topic types 15:11@aschwanden4stc  paragraph  table  body related  body  conbody  refbody  taskbody  Most body elements contain a mix of common things:  section and example  xref and related-links  list related (ul, ol, and li)  figure and image  paragraph and title 40
  41. 41. 7. Task is core to what user do 15:11@aschwanden4stc 41  In almost every situation people turn to docs because they are doing things  They discover a problem and need to look up docs  Highly unlikely people read about what to do when the engine light comes on unless/until the engine light comes on  No one reads how to Create a Concept in DITA unless they need to create concepts. In DITA.  An answer to how that tells the user just what to do and the order in which to do it  Step-by-step instructions that enables a user to actually do something
  42. 42. Select where to add a task (in the map) 15:11@aschwanden4stc 42 1
  43. 43. Let’s add it to the map automatically 15:11@aschwanden4stc 43
  44. 44. Title is “Create a <concept>”, and add shortdesc 15:11@aschwanden4stc 44
  45. 45. Insert a <shortdesc> for the task 15:11@aschwanden4stc 45 Type this: Introduce your audience to an idea before you make them do things. 1 2
  46. 46. +You as the author, –<taskbody>, –<related-links> 15:11@aschwanden4stc 46 1 2
  47. 47. Save and close the “non-map” content 15:11@aschwanden4stc 47
  48. 48. Tasks also contain very specific elements 15:11@aschwanden4stc 48  task related elements o prereq (before you begin) o context (concise reason/benefit) o steps (detailed below) o result (net result of the entire task) o example (specific example of the task) o postreq (once done, additional “must to” items)  steps related elements o steps and steps-unordered, containing one or more step o cmd (specific instruction, call to action) o info (additional content to help user perform the step) o stepresult (specific result of JUST this step, not the task) o tutorialinfo (content to help when working in a guided way) o substeps (one level only, just as needed... Too many? Make a new task!)
  49. 49. How about content contributed by SMEs 15:11@aschwanden4stc  Technical communicators  Good with learning tools  Work with many outputs  Familiar with templates  Comfortable in Word and FrameMaker worlds  Like to learn, dive in, options  Good candidates for work in DITA and FrameMaker  SMEs  Quick contributors  Not interested in all outputs  Simpler interface  Passing familiarity with Word and styles/tags  Let them focus on their job  Good candidates for an easy, simplified DITA workflow 49
  50. 50. 8. References get to facts and details 15:11@aschwanden4stc  The tech stuff you look up when you know the big picture (concept) and the procedure (task), but you don’t recall specific details  Tables, lists, alphabetical  Users should be able to scan quickly and find information  Often technical or background information 50
  51. 51. Remember the SMEs? How can we help them? 15:11@aschwanden4stc 51
  52. 52. This is how easy it SHOULD be for contributors 15:11@aschwanden4stc 52
  53. 53. Let’s enter text under the <concept> title 15:11@aschwanden4stc 53 Type: An idea, a quick overview of something we are documenting.
  54. 54. Add a bit more text in the reference 15:11@aschwanden4stc 54 Type: Clear step-by-step instructions. Only the call to action, no conceptual or reference information.
  55. 55. Several pre-defined elements exist 15:11@aschwanden4stc 55  Toolbars allow specific elements to be added  Icons can be customized  Knowing structure isn’t required  It helps, and in many cases the technical communications team should know it  But now a SME can create DITA valid content  Even new task/concept/reference content can be built
  56. 56. DITA will NOT allow <section> if in a <title> 15:11@aschwanden4stc 56
  57. 57. Simplified XML follows rules, its own way 15:11@aschwanden4stc 57
  58. 58. Add <title> and <para> 15:11@aschwanden4stc 58 Title: <reference> element Para: Technical details, tables, lookup info.
  59. 59. When SMEs are done, content returns to authors 15:11@aschwanden4stc 59  Toggle back to WYSIWYG (from pencil icon to sheet)  Review the reference  In some cases there may be cleanup  Sure beats copy/paste and manual cleanup though  Save and close the file
  60. 60. BTW, tasks and concepts are also supported! 15:11@aschwanden4stc 60
  61. 61. 9. Publish content 15:11@aschwanden4stc  Native FrameMaker  Support is included  Run it by selecting File > Publish  Customize it using  A visual interface 61  DITA OT  Support is included  DITA > Generate DITA OT Output  Customize it using  Scripts  Developers  Code  Debugging
  62. 62. Publish with native FrameMaker 15:11@aschwanden4stc 62
  63. 63. After a bit of wizardry 15:11@aschwanden4stc 63
  64. 64. And to customize this output 15:11@aschwanden4stc 64
  65. 65. From a map, DITA > Generate DITA OT Output 15:11@aschwanden4stc 65 1 2 3 4
  66. 66. Outputs supported in the OT include… 15:11@aschwanden4stc 66
  67. 67. Some stuff happens, and the OT delivers to a folder 15:11@aschwanden4stc 67
  68. 68. Standard help content, right from DITA 15:11@aschwanden4stc 68
  69. 69. Tasks, reference, all converted 15:11@aschwanden4stc 69
  70. 70. And to customize the OT output 15:11@aschwanden4stc  Search (thanks Google!)  To customize <codeblock> to change the font color and background color  Figure out which attributes to change.  A full-text search for "codeblock“ yields a few results, one of which is fo/xsl/pr-domain.xsl  The template is found on line 46: <xsl:template match="*[contains(@class ,' pr-d/codeblock ')]">.  The template shows us we need to modify the "codeblock" attribute set on line 48: <fo:block xsl:use-attribute- sets="codeblock" id="{@id}">  The "codeblock" attribute set is also in fo/cfg/fo/attrs/pr-domain- attr.xsl on line 41: <xsl:attribute-set name="codeblock">  The next step is to customize this attribute set 70
  71. 71. Then we continue to customize it 15:11@aschwanden4stc  Copy fo/Customization/fo/attrs/ custom.xsl.orig to custom.xsl  Copy the codeblock attribute set to the new XSL  Find the code for the background color and font color so we can specify these attributes  The resulting code:  <xsl:attribute- set name="codeblock">  <xsl:attribute name="backgrou nd- color">#ff0000</xsl:attribute>  <xsl:attribute name="color">#ff ffff</xsl:attribute>  </xsl:attribute-set>  Then tell the plugin to use the customizations  Copy /fo/Customization/ catalog.xml.orig to catalog.xml  Open the copied file and edit the 6th row to uncomment the code from:  <!--uri name="cfg:fo/attrs/custom.xsl" uri="fo/attrs/custom.xsl"/-->  to:  <uri name="cfg:fo/xsl/custom.xsl" uri="fo/xsl/custom.xsl">  Save the file  See. It’s easy to write code. 71
  72. 72. 10: Reorg and republish 15:11@aschwanden4stc 72
  73. 73. And, by the way File > Save Ditamap As > ... 15:11@aschwanden4stc 73
  74. 74. You can create FrameMaker content from DITA 15:11@aschwanden4stc 74
  75. 75. If you want, use a simple form to do so 15:11@aschwanden4stc 75
  76. 76. Your takeaway exercises 15:11@aschwanden4stc  With DITA content  Use the map and open files  Add some more content to the tasks, ensuring they are valid (just take baby steps)  Add a <step> or two  Save the files  Publish and review  Publishing FrameMaker  Experiment with settings  Create different outputs  Test the format options  Open content on different devices 76
  77. 77. Summing up the discussion, and options to continue it. @aschwanden4stc 15:11 77 Conclusion and contact
  78. 78. In closing, we covered: 15:11@aschwanden4stc 78 1. Setup of FrameMaker and create a bit of sample content 2. Overview of DITA in a single slide 3. Intro to all core topic types and elements 4. Behind the scenes (attributes) 5. Map 6. Concept 7. Task 8. Reference 9. Publish 10. Update/Publish again!
  79. 79. Considering DITA? 15:11@aschwanden4stc 79  This was under an hour... It isn’t enough to get you going  But it provided ideas to think about  Questions you should explore  Do you even need DITA?  If so, what about the content you have?  Does it need to be cleaned up, re-written, converted?  How do you get your templates into the DITA world?  What about training, support, and potential content management?  The next slide is a great way to start that exploration 
  80. 80. Thank you for your attention 15:11@aschwanden4stc 80 905 833 8448 (Eastern Time) bernard@publishingsmarter.com www.linkedin.com/in/bernardaschwanden @publishsmarter (also aschwanden4stc) www.publishingsmarter.com

×