Enforcing Style Guide Rules for Technical Documents
1 like598 views
The document outlines procedures for enforcing style guide rules in technical documentation projects to ensure consistency and accuracy. It discusses challenges in maintaining document structure and styling, automatic checks for rule compliance, and the implementation of business rules using various schema languages and tools. Additionally, it highlights the benefits of a structured approach to documentation, including efficiency and error reduction across different projects.
Enforcing Style Guide Rules for Technical Documents
- 1. Enforce Style Guide Rules Octavian Nadolu octavian_nadolu@oxygenxml.com @OctavianNadolu
- 2. Enforce Style Guide Rules Overview ● Technical documentation projects ● Achieve accurate, consistent documentation that conforms to your project guidelines ● How to define style guide rules for your documentation projects
- 3. Enforce Style Guide Rules Technical Documentation ● User or system manuals ● Help documentation ● Training material ● Work instructions Can be defined as information about a product.
- 4. Enforce Style Guide Rules Example ● <oXygen/> User Manual ● DITA project ● About 2600 topics
- 5. Enforce Style Guide Rules Documentation Process
- 6. Enforce Style Guide Rules Challenges ● Maintaining consistency for all documents ● Impose a structure and a set of styling rules ● Avoid known issues in documentation output
- 7. Enforce Style Guide Rules Cost-Effciency Documentation Review QA Publish Cost Issues
- 8. Enforce Style Guide Rules Solutions ● Prevent issues by defining rules ● Detect the issues at the earliest editing stage ● Propose consistent solutions to solve the issues
- 9. Enforce Style Guide Rules Impose Structure
- 10. Enforce Style Guide Rules Document Structure Rules ● Impose a document structure using a schema language: – DTD – XML Schema – Relax NG – NVDL ● Oxygen supports all schema languages
- 11. Enforce Style Guide Rules Content Completion and Annotations
- 12. Enforce Style Guide Rules Show Hints ● Signal document structure problems ● Preferences to change the schema-aware options
- 13. Enforce Style Guide Rules Limit the Number of Proposals ● Configure the proposals for elements and attributes ● Lightweight DITA ● Controlled Values & Markup Options ~15 proposals ~90 proposals
- 14. Enforce Style Guide Rules Conclusions ✔ Impose a structure ✔ Suggestions to insert valid markup ✔ Annotations to help you understand what the markup represents ✔ Links to additional information and style guides ✔ Powerful schema-aware support
- 15. Enforce Style Guide Rules Impose Business Rules Rules for your documents that cannot be imposed by the schema Examples: ● Titles should have content ● Consecutive lists are not allowed ● IDs must follow a certain pattern ● Consecutive notes of a same type ● Too many entries in a table row ● Sections must have IDs ● Titles are too long ● ...
- 16. Enforce Style Guide Rules Example ● For <oXygen/> User Manual we defined more than 200 rules.
- 17. Enforce Style Guide Rules Rules Check Challenges ● Documentation team members needs to remember all rules ● Determine if a rule is violated ● Provide also consistent solutions to correct the problems
- 18. Enforce Style Guide Rules Automatic Check Rules Implement automatic checks for rules using Schematron
- 19. Enforce Style Guide Rules Rules for All Documents and Authors
- 20. Enforce Style Guide Rules Example ● Create a simple documentation project ● Apply a set of business rules for all the documents
- 21. Enforce Style Guide Rules Simple Style Rules Styling is not allowed in titles Semicolon is not allowed at the end of a list item Text in the link and the value of the @href are the same
- 22. Enforce Style Guide Rules Editing Consistency Rules Topic ID must be equal to file name All sections should have an @id Consecutive lists are not allowed
- 23. Enforce Style Guide Rules Structure Rules Missing cells in a table Too many nested lists List contains only one item
- 24. Enforce Style Guide Rules Output Related Rules
- 25. Enforce Style Guide Rules Consistent Solutions to Correct Problems ● Business rule messages are not always enough for the user to find a solution ● Solutions to automatically apply business rule constraints
- 26. Enforce Style Guide Rules Business Rule Fixes Implement fix proposals using Schematron QuickFix (SQF) language
- 27. Enforce Style Guide Rules Schematron Quick Fixes Spec www.w3.org/community/quickfix schematron-quickfix.github.io/sqf
- 28. Enforce Style Guide Rules Example ● Create fix proposals for the business rules ● Share the fix proposals with all team
- 29. Enforce Style Guide Rules Create Business Rules using DIM
- 30. Enforce Style Guide Rules Dynamic Information Model (DIM) ● An implementation of an intelligent style guide ● Describes and enforces rules ● Schematron for Information Architects presented by George Bina at XML Prague ● Open source project available on GitHub https://github.com/oxygenxml/dim
- 31. Enforce Style Guide Rules Rules Check Advantages ● Detect the issues at editing time ● Prevent problems in the generated output ● All team follows same rules ● Consistent solutions to correct problems
- 32. Enforce Style Guide Rules Projects Using Business Rules ● Thieme - publishing company uses a custom framework to create and edit XML documents ● parsX - a product developed by pagina GmbH used to facilitate EPUB production ● ART-DECOR - an open source tool suite that supports SDOs active in the healthcare industry Sample SQF embedded in XSD ● ATX custom framework – used by a major automotive manufacturer
- 33. Enforce Style Guide Rules Business Rules Fix Proposals Discover the technology behind the fix proposals for business rules: Defining Schematron Quick Fixes Understanding and Developing Schematron Quick Fixes Schematron Quick Fixes Samples Schematron Quick Fixes Specification
- 34. Enforce Style Guide Rules Thank you! Questions? <oXygen/> XML Editor http://www.oxygenxml.com octavian_nadolu@oxygenxml.com @OctavianNadolu