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.

Best practices when migrating to DITA

443 views

Published on

Advantages to authoring in a topic based environment
*. More efficient
*. Structure helps produce better content
*. Takes advantage of new technologies for delivering content
I plan to share the best way to
*. Assess your current situation
*. Plan for your future and
*. Execute to the plan
After the presentation, you will:
*. Understand what topic–based writing is and its advantages
*. Follow best–practices for organizing new material into topic–based content
*. Understand the place of XML and DITA and how they may relate to your needs

  • Be the first to comment

Best practices when migrating to DITA

  1. 1. Bernard Aschwanden www.publishingsmarter.com bernard@publishingsmarter.com DITA Conversion Best Practices 23:56 1 @publishsmarter
  2. 2. Overall Objectives 23:56@publishsmarter 2  Advantages to authoring in a topic based environment  More efficient  Structure helps produce better content  Takes advantage of new technologies for delivering content  I plan to share the best way to  Assess your current situation  Plan for your future and  Execute to the plan  After the presentation, you will:  Understand what topic–based writing is and its advantages  Follow best–practices for organizing new material into topic–based content  Understand the place of XML and DITA and how they may relate to your needs
  3. 3. Housekeeping and note taking 23:56@publishsmarter 3  Not all slides or topics are equally weighted  Use some, discard others  Slides speed varies (reference)  Questions? Ask along the way!  I’d love to claim errors/typos is on purpose… they isn’t, ain’t, and weren’t never; however, I’ll fix ‘em as I can…
  4. 4. About your speaker 23:56@publishsmarter 4  Publishing Smarter: President  Content strategist, publishing technologies expert, author, and geek- enough  Certified Technical Trainer  DITA  Content management  Topic-based writing  Society for Technical Communication  Vice President  STC Associate Fellow
  5. 5. Standard disclaimer 23:56@publishsmarter 5  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)
  6. 6. The initial goodies @publishsmarter 23:56 6 Topic-based writing
  7. 7. Topic-based single sourcing is more efficient 23:56@publishsmarter 7  Use the same content in more than one location  This could be across:  Output types (online help, user’s guide)  Perhaps graphics are excluded, or specific topics not needed/added  Projects (new version re-uses content from last version)  Products (t40 and t41 are similar products, 90% the same)  Departments (Marketing re-uses Doc’s content)  User types (novice and advanced users)  Operating systems (Windows, Mac, Unix, Android)  Many instances of the same topics, unique order
  8. 8. If you single source 23:56@publishsmarter 8  Try to share topics in their entirety  Create content that is free of ‘specifics’  Product names  Screen shots  Other identifying content  If you need specifics, can you conditionalize ‘chunks’  Entire sections  Paragraphs  Images
  9. 9. Basic sample 23:56@publishsmarter 9
  10. 10. Defining topic-based writing 23:56@publishsmarter 10  A way to create content from standalone topics which are:  Smallest possible unit of information that makes sense on its own (no absolute dependencies)  Reusable as a standalone unit of information  Based on information type (e.g., concept, reference, task)  Can be assembled to create help, HTML, PDF, etc  Linked and referenced to build relationships  Not applicable to all doc types though  Marketing, legal, regulatory may be far more focused  However, ideas can still apply (targeted writing)
  11. 11. Reasons topic-based is a good idea 23:56@publishsmarter 11  An alternative to linear writing  Traditional book model  Writing in chapters  Order matters (before/after)  A method of focusing on your users’ needs  A way to chunk information based on types  Fundamentally, a way of organizing your content into easily digestible pieces
  12. 12. The linear approach to content 23:56@publishsmarter  Linear means:  Content is related to previous and following content  It's not easy to re-order  If you do NOT know the order, then the context can be lost very quickly 12
  13. 13. The modular (topic-based) approach to content 23:56@publishsmarter  Modular means:  Pieces of information must make sense without context  Pieces of information can be moved around  Context may or may not bring extra meaning to individual pieces  People jump in where and when they need content 13
  14. 14. Benefits to writers and users 23:56@publishsmarter  To the writer  Team collaboration  Easier review cycle  Create it faster  Solid time management  Less time formatting  Share content  Shorter content  Fewer opportunities for mistakes  To the user  Read what you want  Read in the order you want  Common layout makes it fast to scan and find content (beyond search) 14
  15. 15. It makes content better @publishsmarter 23:56 15 Structure (and XML)
  16. 16. XML supports structured writing 23:56@publishsmarter 16  Structure implies a set of defined rules (law, math, engineering, grammar)  Writing implies the creation of content  Structured content consistently follows rules  A good foundation results in a happy home
  17. 17. What does it look like? 23:56@publishsmarter 17  Looks a lot like HTML (or it can)  <p>This sample <i>ain’t</i> perfect; just basic ideas.</p> It’s a <p>aragraph, and has some <i>talic content in it. The </i>talic content ends, then the </p>aragraph ends.  <img src=“logo.gif” height=“100” width=“50” />  Let’s dissect an element Part Function img Name of the element src Name of an attribute logo.gif Value of the attribute
  18. 18. What does it look like? 23:56@publishsmarter 18  Looks a lot like HTML (or it can)  <p>This sample <i>ain’t</i> perfect; just basic ideas.</p> It’s a <p>aragraph, and has some <i>talic content in it. The </i>talic content ends, then the </p>aragraph ends.  <img src=“logo.gif” height=“100” width=“50” />  Let’s dissect an element Part Function img Name of the element src Name of an attribute logo.gif Value of the attribute
  19. 19. What does it look like? 23:56@publishsmarter 19  Looks a lot like HTML (or it can)  <p>This sample <i>ain’t</i> perfect; just basic ideas.</p> It’s a <p>aragraph, and has some <i>talic content in it. The </i>talic content ends, then the </p>aragraph ends.  <img src=“logo.gif” height=“100” width=“50” />  Let’s dissect an element Part Function img Name of the element src Name of an attribute logo.gif Value of the attribute
  20. 20. What does it look like? 23:56@publishsmarter 20  Looks a lot like HTML (or it can)  <p>This sample <i>ain’t</i> perfect; just basic ideas.</p> It’s a <p>aragraph, and has some <i>talic content in it. The </i>talic content ends, then the </p>aragraph ends.  <img src=“logo.gif” height=“100” width=“50” />  Let’s dissect an element Part Function img Name of the element src Name of an attribute logo.gif Value of the attribute
  21. 21. Human usable XML might look more like this 23:56@publishsmarter 21 <?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE task PUBLIC "-//OASIS//DTD DITA Task//EN" "technicalContent/dtd/task.dtd" []> <task id="id_t_lighting_lvl"> <title>Adjust lighting levels</title> <shortdesc>Room or seat brightness can be individually configured.</shortdesc> <taskbody> <context><indexterm audience="EndUser">lighting</indexterm><p audience="EndUser“> For safety, admins can override preferences.</p><p audience="Administrator">You can override any personal preferences.</p></context> <steps> <step><cmd>Select <uicontrol>Lighting Configuration</uicontrol>.</cmd></step> <step><cmd>Tap <uicontrol>Layout</uicontrol>.</cmd> <info audience="Administrator"> <p>To set global levels, tap <uicontrol>Override all Layouts</uicontrol>.</p> </info> </step> <step> <cmd>Tap the appropriate light level or configuration.</cmd> </step> </steps> </taskbody> </task>
  22. 22. Reading it can be pretty simple (ignore code) 23:56@publishsmarter 22 <?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE task PUBLIC "-//OASIS//DTD DITA Task//EN" "technicalContent/dtd/task.dtd" []> <task id="id_t_lighting_lvl"> <title>Adjust lighting levels</title> <shortdesc>Room or seat brightness can be individually configured.</shortdesc> <taskbody> <context><indexterm audience="EndUser">lighting</indexterm><p audience="EndUser"> For safety, admins can override preferences.</p><p audience="Administrator">You can override any personal preferences.</p></context> <steps> <step><cmd>Select <uicontrol>Lighting Configuration</uicontrol>.</cmd></step> <step><cmd>Tap <uicontrol>Layout</uicontrol>.</cmd> <info audience="Administrator"> <p>To set global levels, tap <uicontrol>Override all Layouts</uicontrol>.</p> </info> </step> <step> <cmd>Tap the appropriate light level or configuration.</cmd> </step> </steps> </taskbody> </task>
  23. 23. Structure has some human-friendly feel to it 23:56@publishsmarter 23 <?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE task PUBLIC "-//OASIS//DTD DITA Task//EN" "technicalContent/dtd/task.dtd" []> <task id="id_t_lighting_lvl"> <title>Adjust lighting levels</title> <shortdesc>Room or seat brightness can be individually configured.</shortdesc> <taskbody> <context><indexterm audience="EndUser">lighting</indexterm><p audience="EndUser"> For safety, admins can override preferences.</p><p audience="Administrator">You can override any personal preferences.</p></context> <steps> <step><cmd>Select <uicontrol>Lighting Configuration</uicontrol>.</cmd></step> <step><cmd>Tap <uicontrol>Layout</uicontrol>.</cmd> <info audience="Administrator"> <p>To set global levels, tap <uicontrol>Override all Layouts</uicontrol>.</p> </info> </step> <step> <cmd>Tap the appropriate light level or configuration.</cmd> </step> </steps> </taskbody> </task>
  24. 24. You can even understand the attributes 23:56@publishsmarter 24 <?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE task PUBLIC "-//OASIS//DTD DITA Task//EN" "technicalContent/dtd/task.dtd" []> <task id="id_t_lighting_lvl"> <title>Adjust lighting levels</title> <shortdesc>Room or seat brightness can be individually configured.</shortdesc> <taskbody> <context><indexterm audience="EndUser">lighting</indexterm><p audience="EndUser"> For safety, admins can override preferences.</p><p audience="Administrator">You can override any personal preferences.</p></context> <steps> <step><cmd>Select <uicontrol>Lighting Configuration</uicontrol>.</cmd></step> <step><cmd>Tap <uicontrol>Layout</uicontrol>.</cmd> <info audience="Administrator"> <p>To set global levels, tap <uicontrol>Override all Layouts</uicontrol>.</p> </info> </step> <step> <cmd>Tap the appropriate light level or configuration.</cmd> </step> </steps> </taskbody> </task>
  25. 25. Remember that XML provides a division 23:56@publishsmarter 25 Format Content
  26. 26. With XML you spend your time wisely 23:56@publishsmarter 26
  27. 27. There ARE better ways to write, so take advantage of them! @publishsmarter 23:56 27 New technologies
  28. 28. Notepad. You can edit with Notepad. Woo. Hoo. 23:56@publishsmarter 28
  29. 29. Code view if you want/need it 23:56@publishsmarter 29
  30. 30. Code view is only one option 23:56@publishsmarter 30
  31. 31. Across multiple tools 23:56@publishsmarter 31
  32. 32. Mainstream tools offer a lot of support 23:56@publishsmarter 32
  33. 33. All the code is still there... 23:56@publishsmarter 33
  34. 34. You can choose to show JUST the EndUser 23:56@publishsmarter 34
  35. 35. Show and hide based on attributes and values 23:56@publishsmarter 35
  36. 36. Or choose just Administrator content 23:56@publishsmarter 36
  37. 37. Display audience specific content 23:56@publishsmarter 37
  38. 38. Net benefit of two topics, one source 23:56@publishsmarter 38  Less editing  Fewer edits  Less review time  Quicker approvals  Fewer overall words to manage  And, as the content is created, you can publish to any output that you need!
  39. 39. It is not output restrictive 23:56@publishsmarter
  40. 40. Converted content can be on tablets
  41. 41. Or on phones; it’s device independent
  42. 42. High level ideas on the day-to-day writing of content @publishsmarter 23:56 42 How to think about DITA
  43. 43. DITA in a single slide 23:56@publishsmarter 43  D is for Darwin  Evolves and adapts, over time DITA is adding new topic types, elements, as well as tools and best practices  Specializes, when it can’t meet your needs, you can customize  IT is for Information Typing  Info is organized/classified into task/concept/reference  A is for Architecture  A formal set of rules  Planned and developed  DITA is primarily about Topics and Maps (and planning) Connect People and Content
  44. 44. Identify topic types 23:56@publishsmarter 44  topic: A meaningful, stand–alone unit of information, eg. Work with images  three primary topic types matter  task: Procedural details such as step-by-step instructions. eg. Import images, Resize images  concept: Background info that users need to know. eg. Reasons to use images  reference: Quick access to tech info, or facts. eg. Supported image formats, Raster versus vector  map: Contains info about relationships between topics, appropriate metadata, and optional linking and navigation TOPIC REFERENCECONCEPT TASK
  45. 45. DITA begins with thinking of tasks 23:56@publishsmarter 45  The task identifies the best practice to follow to achieve a goal  Step-by-step  Minimal other information
  46. 46. If needed, concepts support tasks 23:56@publishsmarter 46  The concept introduces the ideas  Answers the questions of “what is” or “why would I” that people have
  47. 47. For technical info, references help 23:56@publishsmarter 47  Quick access to facts  Usually a lookup for people who know the concept, understand the task, but need the quick technical specs
  48. 48. Maps 23:56@publishsmarter  Create a relationship between topics  Used for navigation, publishing and more 48
  49. 49. When topics and maps come together 23:56@publishsmarter  A resulting hierarchy of information exists  Materials are easier to read, quicker to scan  When published, delivers minimalist, clear, and easy to use content  The result of using DITA is more than just clear content  Navigation between topics automatic  Further navigation can also be developed 49 TOPIC REFERENCECONCEPTTASK
  50. 50. Best practices While they are BEST practices, there is a formal approach to them in DITA @publishsmarter 23:56 50 Things you can do to start
  51. 51. Quick steps to ID what you actually have 23:56@publishsmarter 51  Review your table of contents  Build a TOC with steps, figures, tables in it  Review it again  Start to quickly ID  See if you can guess what is a task/concept/reference  Compare your TOC info with the body of the content  If there isn’t a match that is a clear T, C, R, then rework (ideas follow)
  52. 52. Tasks are core in DITA 23:56@publishsmarter 52  Remember that tasks are a core part of DITA  Odds are people are doing things when they discover a need to look up docs  Tasks are the most likely place users turn  Make sure you explain the “how to” and support that with other information
  53. 53. Best practices (both DITA and minimalism) 23:56@publishsmarter 53  Stick to one way to tell people how to do it  Don’t mix icons, shortcuts, and menus in a task (I like Select File > Open. Menus rarely are customized/hidden unlike keyboard commands or toolbars) BTW: Good design is also good minimalism!  Avoid features (that’s concept)  <cmd> is 1 sentence  If needed, 1 level of substeps  Avoid stem sentence lead-ins  Best: Clear title, familiar patterns  Less to translate and manage
  54. 54. Rework a source quickly 23:56@publishsmarter 54  Take the next slide and mark it up  Use (color, bold, italic, whatever…) to ID topic type  Task, concept, or reference identifiers  Rework into core task/concept/reference  This is an online exercise, and I’ll use the chat, but you can do this on your own with your content too!  Later: Find a good sample of your own content, and try this for yourself
  55. 55. 23:56@publishsmarter 55 Microsoft Word, Excel, and PowerPoint allow you to insert a graphic. Graphical images add value to documents by making it easier to see any type of idea represented as a picture. They also break up content rich materials. Many formats (including common ones like jpg, gif, bmp, or even pdf) are supported in most of the tools. To insert an image in any one of these applications you can use the Insert menu and choose Picture after you select a location. Then choose and import an image in one of the supported formats. Make sure you manage graphics well! You may want one folder for all your images instead of looking everywhere for them.
  56. 56. 23:56@publishsmarter 56Microsoft Word, Excel, and PowerPoint allow you to insert a graphic. Graphical images add value to documents by making it easier to see any type of idea represented as a picture. They also break up content rich materials. Many formats (including common ones like jpg, gif, bmp, or even pdf) are supported in most of the tools. To insert an image in any one of these applications you can use the Insert menu and choose Picture after you select a location. Then choose and import an image in one of the supported formats. Make sure you manage graphics well! You may want one folder for all your images instead of looking everywhere for them. Task Concept Reference Undecided
  57. 57. 23:56@publishsmarter 57Microsoft Word, Excel, and PowerPoint allow you to insert a graphic. Task: To insert an image in any one of these applications you can use the Insert menu and choose Picture after you select a location. Then choose and import an image in one of the supported formats. Concept: Graphical images add value to documents by making it easier to see any type of idea represented as a picture. They also break up content rich materials. Make sure you manage graphics well! You may want one folder for all your images instead of looking everywhere for them. Reference: Many formats (including common ones like jpg, gif, bmp, or even pdf) are supported in most of the tools.
  58. 58. Add linked pictures (Task) 23:56@publishsmarter 58 Linked graphics ensure that when a source changes, your documents remain current. Prerequisite: Use specific tools to create images first; then add images as needed. 1. Choose a location for an image 2. Select Insert > Picture 3. Choose an image type 4. Double click the image to import When done: Position or size the image.
  59. 59. Reasons to use graphics (Concept) 23:56@publishsmarter 59 Graphics add value to documents by making it easier to see ideas represented visually. They also break up text rich materials. TIP: Manage graphics well! You may want one image folder with all images instead of looking everywhere for them.
  60. 60. Supported formats (Reference) 23:56@publishsmarter 60 Multiple image formats can be imported. Type Value Description Raster image: Joint Photographic Experts Group jpg or jpeg Often used online, good for photos or gradient based images, high color definition support Raster image: Graphics Interchange Format gif Often used online, good for basic image, up to 256 color support, includes transparency
  61. 61. Work with graphics (Topic) 23:56@publishsmarter 61 Microsoft Word, Excel, and PowerPoint allow you to insert a graphic.
  62. 62. Pulling those topics into a map and publishing to multiple outputs... @publishsmarter 23:56 62 Bring it home...
  63. 63. In Serna 23:56@publishsmarter 63  Document > New > DITA 1.1 > Topic  View > Show Markup
  64. 64. In XMetaL 23:56@publishsmarter 64  File > New > DITA Topic > Reference  Add content, use Table > Insert Rows or Columns
  65. 65. In Oxygen 23:56@publishsmarter 65  File > New...  Create a concept, populate it
  66. 66. In FrameMaker 23:56@publishsmarter 66  DITA > New DITA File > New <task> and View > Element Boundaries as Tags, the populate task (if desired, also show Element > Catalog and Structure Tools > Structure View  Tutorials: www.publishingsmarter.com
  67. 67. In FrameMaker 23:56@publishsmarter 67
  68. 68. If you build a map, you can also publish it all 23:56@publishsmarter 68
  69. 69. Summing up the discussion, and options to continue it. @publishsmarter 23:56 69 Conclusion and contact
  70. 70. Overall Objectives 23:56@publishsmarter 70  Advantages to authoring in a topic based environment  More efficient  Structure helps produce better content  Takes advantage of new technologies for delivering content  I plan to share the best way to  Assess your current situation  Plan for your future and  Execute to the plan  After the presentation, you will:  Understand what topic–based writing is and its advantages  Follow best–practices for organizing new material into topic–based content  Understand the place of XML and DITA and how they may relate to your needs
  71. 71. Follow up contact information 23:56@publishsmarter 71 905 833 8448 (Eastern Time) bernard@publishingsmarter.com www.linkedin.com/in/bernardaschwanden @publishsmarter www.publishingsmarter.com

×