Uploaded bydclsocialmedia
Optimizing the DITA Authoring Experience
The document discusses optimizing the DITA authoring experience, highlighting challenges faced by writers due to DITA's complexity and numerous semantic elements. It outlines solutions such as simplifying DITA, creating information models, and developing templates to guide authors effectively. Best practices are also provided for managing constraints, specializations, and utilizing technologies like Schematron for validation.
More Related Content
Similar to Optimizing the DITA Authoring Experience
Optimizing the DITA Authoring Experience
- 1. © 2015 ComtechServices, Inc. 1 Optimizing the DITA Authoring Experience Scott Hudson Senior Consultant Comtech Services
- 2. © 2015 ComtechServices, Inc. 2 Valuable Content Transformed • Document Digitization • XML and HTML Conversion • eBook Production • Hosted Solutions • Big Data Automation • Conversion Management • Editorial Services • Harmonizer
- 3. © 2015 ComtechServices, Inc. 3 Experience the DCL Difference DCL blends years of conversion experience with cutting-edge technology and the infrastructure to make the process easy and efficient. • World-Class Services • Leading-Edge Technology • Unparalleled Infrastructure • US-Based Management • Complex-Content Expertise • 24/7 Online Project Tracking • Automated Quality Control • Global Capabilities
- 4. © 2015 ComtechServices, Inc. 4 We Serve a Very Broad Client Base . . .
- 5. © 2015 ComtechServices, Inc. 5 . . . Spanning All Industries • Aerospace • Associations • Defense • Distribution • Education • Financial • Government • Libraries • Life Sciences • Manufacturing • Medical • Museums • Periodicals • Professional • Publishing • Reference • Research • Societies • Software • STM • Technology • Telecommunications • Universities • Utilities
- 6. © 2015 ComtechServices, Inc. 6 The problem With over 500 semantic elements, how can a writer remember what they are all for? It’s not the way I’m used to writing. It stifles my creativity. The complexity of DITA forms a barrier to new adopters and casual contributors. DITA is too restrictive. There are too many rules, standards, and validations.
- 7. © 2015 ComtechServices, Inc. 7 What do we do about it? • Simplify • Lightweight DITA initiative? • Choose what you need • Provide guidance • Limit what’s available • Provide real-time feedback • Use familiar semantics • Enforce your business rules
- 8. © 2015 ComtechServices, Inc. 8 What do we do about it? • Guide • Choose what you need • Provide guidance • Enforce • Limit what’s available • Provide real-time feedback • Use familiar semantics • Enforce your business rules Information Model Templates Constraints Schematron Specialization Subject scheme
- 9. © 2015 ComtechServices, Inc. 9 Information model • A set of specifications that defines • The structure of your information • The architectural elements to be used • The expected outputs • The required functionality of your authoring environment
- 10. © 2015 ComtechServices, Inc. 10 Information model Information types The standard categories of content that you use to provide the structure and content guidelines needed to author individual topics Content units The building blocks of your information types Metadata dimensions The categories that you use to organize and label the content that you will manage in a content management system Relationships The way in which information types and content units inter-relate to each other
- 11. © 2015 ComtechServices, Inc. 11 Information model
- 12. © 2015 ComtechServices, Inc. 12 Information model: Best practices • Not optional! • Create before choosing tools and employing any other optimization techniques • Include authoring guidelines • Test with a pilot project • Establish a change control process
- 13. © 2015 ComtechServices, Inc. 13 Templates • Serve as a starting point for a new topic • Contain required elements in the correct order • Remove need for authors to distinguish between elements
- 14. © 2015 ComtechServices, Inc. 14 Templates
- 15. © 2015 ComtechServices, Inc. 15 Templates Information Type • Validated by DTD • If structure not followed or correct elements not used, content is invalid Template • Specific implementation of an information type • Validated by the information type DTD • If template structure not followed, content may still be valid
- 16. © 2015 ComtechServices, Inc. 16 Templates: Best practices • Incorporate your authoring standards in comments • Provide default values for metadata • Include all required elements in the recommended order, but leave out options • Base on real-world needs, not what’s possible
- 17. © 2015 ComtechServices, Inc. 17 What do we do about it? • Guide • Choose what you need • Provide guidance • Enforce • Limit what’s available • Provide real-time feedback • Use familiar semantics • Enforce your business rules Information Model Templates Constraints Schematron Specialization Subject scheme
- 18. © 2015 ComtechServices, Inc. 18 Shells • Keep what you want • Get rid of what you don’t want • Add what’s missing • Reduce the chaos
- 19. © 2015 ComtechServices, Inc. 19 Structure of Constrained DTD Shells Header Public Identifier Topic Entity Declarations Constrained Domain Entity Declarations Domain Entity Declarations Domain Attribute Declarations Domain Extensions Topic Nesting Override Domains Attribute Override Content Constraint Integration Topic Element Integration Domain Element Integration MODULE: Company DITA Concept DTD PUBLIC "-//Company//DTD DITA Concept DTD//EN" <!ENTITY % concept-dec PUBLIC "-//OASIS//ENTITIES DITA 1.2 Concept//EN" "concept.ent" >%concept-dec; <!ENTITY % basicHighlight-c-dec SYSTEM "basicHighlightConstraint.ent" >%basicHighlight-c-dec; <!ENTITY % hi-d-dec PUBLIC "-//OASIS//ENTITIES DITA 1.2 Highlight Domain//EN" "../../base/dtd/highlightDomain.ent" >%hi-d-dec; <!ENTITY % base-attribute-extensions "" > <!ENTITY % keyword "keyword | %pr-c-keyword; | %basicSoftware-c-keyword; | %ui-c-keyword; "> <!ENTITY % concept-info-types "concept" > <!ENTITY included-domains "&concept-att; &hi-d-att; &basicHighlight-c-att; “> <!ENTITY % requireTitleSection-c-mod SYSTEM "SectionConstraint.mod"> %requireTitleSection-c-mod; <!ENTITY % concept-typemod PUBLIC "-//OASIS//ELEMENTS DITA 1.2 Concept//EN" "concept.mod"> %concept-typemod; <!ENTITY % hi-d-def PUBLIC "-//OASIS//ELEMENTS DITA 1.2 Highlight Domain//EN" "../../base/dtd/highlightDomain.mod" >%hi-d-def;
- 20. © 2015 ComtechServices, Inc. 20 Shells: Best practices • Create multiple shells based on • author roles and responsibilities • department • deliverable type • Validate templates against specific shells • Create in RelaxNG and generate your DTD or XSD (DITA 1.3)
- 21. © 2015 ComtechServices, Inc. 21 Schematron • Schematron is an ISO/IEC Standard that can be implemented in the authoring tools to • validate an xml structure in accordance with your specific authoring rules • validate the number of allowed elements in a particular xml structure • validate elements based on their location and hierarchy in an xml structure • deliver error messages so users know why their xml is not valid in a particular xml structure
- 22. © 2015 ComtechServices, Inc. 22 Schematron
- 23. © 2015 ComtechServices, Inc. 23 Schematron: Best practices • Use when you can’t enforce business rules or content with the DTD/Schema • Use when you face editorial staff bottlenecks • Use to catch consistent, repetitive issues across writing staff • Use to minimize budget for linguistic analysis tools
- 24. © 2015 ComtechServices, Inc. 24 Subject scheme maps • Define the attribute values an author can select through a “pick-list” of allowed values • Enforce metadata consistency across an organization • Enable hierarchy to be defined for related values
- 25. © 2015 ComtechServices, Inc. 25 Subject scheme maps
- 26. © 2015 ComtechServices, Inc. 26 Subject scheme maps: Best practices • Choose values based on whether users want to search and limit by this particular type of subject • Ensure the majority of your content can be described by this type of subject • Where possible use industry standard controlled vocabulary • Provide a controlled vocabulary (ie picklist) in lieu of open text entry when choices are limited and stable
- 27. © 2015 ComtechServices, Inc. 27 Constraints • Limit your choices to the elements supported by the information model • Enforce required elements and order, where DITA DTD itself may not
- 28. © 2015 ComtechServices, Inc. 28 Constraints
- 29. © 2015 ComtechServices, Inc. 29 Constraints: Best practices • Wait until the information model has been vetted to avoid frequent changes • Eliminate at the highest level, but require at the lowest level • Restrict context when you can’t eliminate entirely • Ensure you have a robust sample topic set for testing
- 30. © 2015 ComtechServices, Inc. 30 Specializations • Redefine content models • Create new • information types • domain-specific elements • attributes • Enforce specific business needs
- 31. © 2015 ComtechServices, Inc. 31 Specializations <!ATTLIST musicCollection %global-atts; class CDATA "- topic/topic reference/reference musicCollection/musicCollection " > <!ATTLIST musicBody %global-atts; class CDATA "- topic/body reference/refbody musicCollection/musicBody " > <!ATTLIST cdList %global- atts; class CDATA "- topic/simpletable reference/properties musicCollection/cdList "> <!ATTLIST cdHeader %global- atts; class CDATA "- topic/sthead reference/prophead musicCollection/cdHeader " > <!ATTLIST artistHeader %global- atts; class CDATA "- topic/stentry reference/proptypehd musicCollection/artistHeader " > <!ATTLIST albumsHeader %global-atts; class CDATA "- topic/stentry reference/propvaluehd musicCollection/albumsHeader " > <!ATTLIST commentsHeader %global-atts; class CDATA "- topic/stentry reference/propdeschd musicCollection/commentsHeader " > <!ATTLIST cdRow %global-atts; class CDATA "- topic/strow reference/property musicCollection/cdRow " > <!ATTLIST artist %global- atts; class CDATA "- topic/stentry reference/proptype musicCollection/artist "> <!ATTLIST albums %global-atts; class CDATA "- topic/stentry reference/propvalue musicCollection/albums ">
- 32. © 2015 ComtechServices, Inc. 32 Specializations: Best practices • Use all other options first; not to be taken lightly • Make sure a specialization doesn’t already exist • Search open source for shared solutions • Share your solution with the community if you must start from scratch
- 33. © 2015 ComtechServices, Inc. 33 Relax There are mechanisms in place to simplify DITA right now – we just need to use them!
- 34. © 2015 ComtechServices, Inc. 34 Questions? Scott Hudson 303/232-7586 scott.hudson@comtech-serv.com @shudson310 http://www.scott-hudson.branded.me
- 35. © 2015 ComtechServices, Inc. 35 Upcoming Events • New CIDM Online Conference: • July 29: https://forum.infomanagementcenter.com • Conferences: www.infomanagementcenter.com • Best Practices: September 21-23 in St. Petersburg, Florida • DITA Europe: November 16-17 in Munich, Germany • CMS/DITA North America: April 20-22 in Chicago, Illinois • Workshops: http://comtech-serv.com • Minimalism: June 2-3 in San Jose, CA • DITA Getting Started: July 21-22 in Wakefield, MA • Optimizing the DITA Authoring Experience: July 23-24 in Wakefield, MA • Content Management Strategies: September 10-11 in Philadelphia, PA • Information Modeling for Topic-Based Authoring: October 12-13 in Indianapolis, IN
Editor's Notes
- #2 The DITA standard is comprised of more than 530 elements. How does an author choose the appropriate elements to use when marking up structured content? What if DITA is still missing business or industry-specific elements that you need? Companies often use editorial style guides to help authors, but how can you consistently enforce those rules, especially with limited editorial staff? You want authors to reuse information, but how do you ensure consistency in metadata tagging across the organization so they can easily locate reusable information? DITA offers a variety of ways to optimize your authoring experience, making it as simple as possible for your authors to create and publish content that conforms to your information model and authoring guidelines. But which ones are most effective in what situations? This webinar compares and contrasts the ways of customizing your authoring environment and provides guidelines for their use.
- #7 In today’s technical authoring world, there are many challenges to overcome. Add on top of that a requirement to change to structured authoring, and you will hear a litany of issues! Some authors say that structured authoring stifles their creativity, others say they have a hard enough time getting contributions from subject matter experts and other organizations! Some say DITA is too restrictive and that there are too many rules and standards to remember. With over 500 semantic elements, how can a writer remember the right situations to use those particular elements?!
- #8 In this modern tech comm era, we are here to help! The key is Simplification. We’ve heard a number of these concerns and complaints, to such an extent, that even the DITA Technical Committee has launched a Lightweight DITA initiative as one approach to solve these problems. But do we even need it? There are variety of modern tools to optimize your authoring experience, making it as simple as possible for your authors to create and publish content that conforms to your information model and authoring guidelines. What if I told you there was a way to choose exactly what you need; a way to provide better guidance to your authors, a way to pare down the 500 semantic elements, to provide editorial feedback as your authors are writing? What about the ability to use semantic tags from your particular industry or company, and a way to enforce your business requirements?
- #9 Well, look no further! These tools exist today and can greatly improve the authoring experience! When we talk about Simplification, there are really 2 major areas to address: Guidance and Enforcement. Let me introduce you to the technologies that will help. In order to choose what you need, you need to define it. Enter the Information Model! We’ll talk more about this shortly. One of the best ways to provide guidance is through examples. Templates provide both a starting point, and directions. In the enforcement arena, you can limit the number of elements using DITA Constraints. You may also want to limit the set of values that can be assigned to attributes or metadata. DITA subjectSchemes are a perfect application for this. What if you want to provide real-time feedback and enforce business content rules? Schematron is not part of the DITA standard, rather it is a perfect companion XML standard. Finally, the ability to use tag names that have specific meaning for your company or industry. DITA Specialization is the key technology to create your own tagset while remaining fully DITA-compliant. Let’s take a tour through each of these new modern conveniences.
- #10 Choose what you need… Create an information model as a way to guide your authors. An info model defines the structure of your information. It defines what elements and attributes should be used to create the content, and what you can expect on the other side of the equation. It also will help to define the functionality you will need in your authoring. It is a living document.
- #11 Your information model is comprised of a number of different “layers”. It defines the Metadata you use to organize and classify your content, to help with searching for Reuse – a part of the next layer. Your info model should define how to create relationships between content, how they should be assembled together and where they can be reused. The info model will define the types of content that authors should create. These could be the standard DITA concept, task and reference, or additionally learning objects, troubleshooting and more! At the next level of detail, the info model will define the individual semantic elements that should be used within each information type.
- #12 In this example, you can see this info model places different requirements on elements than base DITA defines. The information model describes the specific needs for your company and how you want your organization to create content using DITA. This example is a very small section of a much larger info model. The info model should provide enough detail that an author can easily reference when creating content.
- #13 Just like a master-planned community, use these best practices to design and blueprint your content! This should never be optional. Every authoring group should have a defined info model, and it should be created FIRST! Don’t learn the hard way by buying a tool first and then trying to figure out how to use it. Rather, define the desired state. Create the plan, then apply the other optimization techniques to that plan. Include authoring guidelines on voice, titling, verb usage, etc. Test it out with a pilot project and make sure it meets your needs. Then, once it is defined, you should establish a change control board or process to minimize thrash and ensure buy-in for any changes to the info model.
- #14 Once your info model has been created, create authoring templates. These are based off a DTD or schema. Remember, a template will validate or enforce according to the DTD, not the template. That means it is meant to be used as a starting point for new topics. It should contain all of the required elements that you want, in the correct order. It’s not meant to be a kitchen sink of all the possible examples, but a best-case or typical structure for that kind of topic – so that it just needs the details to be filled out. Templates remove the need for authors to compare elements in the DITA spec.
- #15 Notice in this template that it provides the necessary structures, as well as comments (in the boxes) to guide the author in what content is expected in each location of the document.
- #16 How important is it for authors to follow the template? An Information Type (think topic type) validates against a DTD or schema, and content MUST follow the rules of the schema. A template provides a specific example or starting point for authors to create content. It is based on an information type and validated against the DTD. If the author removes content from the template, it may still be valid against the DTD. It’s a suggested starting point, rather than a hard and fast set of content rules.
- #17 Bookmap templates for default values Different templates for different content types Remember, this should not be the kitchen sink, but a specific example of the content you want.
- #18 Just a quick “refresher” on the Simplification strategy. We just talked about the modern “Guidance” conveniences. Now we need to get tough and talk about Enforcement!
- #19 Shells are the “Enforcers”
- #21 Where corporate model is flexible, specific departments may not be
- #23 Schematron is made up of patterns and rules. Rules can report on specific conditions or values, or assert that a condition must exist. Any time a rule is triggered, it can return a warning or an error. It’s a good practice to determine what business rules should be the “please double check this” (i.e. Warnings) and which should be “stop the presses” (i.e. Errors). Example: Rules can be layered: 50 custom rules, 41 Microsoft Manual of Style , 240 Apple Style Guide rules, 27 DITA Best Practice rules.
- #24 Think of schematron as an automated “editorial bot” to make sure your content is crystal clean!
- #25 Our next modern convenience enable “pick lists” for attribute values. Use subjectScheme when you need metadata values to be consistently applied. Can you guarantee that authors will always use lowercase? Init cap? Title case? If there is a possibility of human error, reduce the chance of error through a controlled vocabulary, as implemented using subjectSchemes. Schemes also enable you to create a taxonomy for your information.
- #26 Notice in this subjectScheme, an audience attribute is limited to a specific list of user roles, “installer, operator, technician level 1, technician level 2 and administrator. An authors choices for the audience metadata would be limited to these values.
- #27 Example: DublinCore, Library of Congress thesarii, and MeSH (medical subject headings), PRISM source vocabulary and more Example: <category> in DITA vs <author>
- #28 Ease tag overload for writers Lock down specific attribute value choices
- #29 In this example constraint, you can see that the Constraint model further restricts the Software domain elements to userinput, systemoutput, cmdname and varname. A much smaller subset than the full DITA standard provides out of the box!
- #30 Example: Require mainbooktitle, don’t have to require booktitle beause you can fulfill mainbooktitle without booktitle Eliminate sl, don’t have to eliminate sli Restrict example – only want table footnotes, restrict fn to <table> or <entry>
- #32 In this example, you can see a Music collection specialization. With specializations, you must provide a “fallback” for your content models. In other words, they have to be based on one of the existing base DITA content models. When you do this, it enables your specialization to be reused and rendered, even if the specific rendering plugin designed for your specialization is not available. Notice that musicCollection is based on reference, which is based on topic. The challenge with specialization, is that you need to know enough about the base DITA models to find the structure that is similar to what you are trying to model. As you can see, specialization code can be a little complex, too! The good news: in DITA 1.3, specializations should be easier to create in the new native RelaxNG format, from which you can generate DTDs and XSDs if your authoring tool requires it.
- #33 Machine industry, L&T, troubleshooting are all Official specializations. MusicCollection is an example of an open source specialization, as is the DITA4Publishers
- #34 As we end our Optimization tour of modern DITA conveniences, take a deep breath and relax! The tools you need are already available today! We just need to start using them.
- #35 If you have questions following this webinar, please contact me at Comtech, or check out my twitter feed, LinkedIn or Branded.me
- #36 If you would like in-depth training on how to implement any of these technologies I mentioned today, we offer a full 2-day course to provide hands-on experience. Just contact us to find out more! Thanks again to DCL for hosting this webinar.