How should a Happy and Healthy Documentation Project Look Like?
Do you have a Healthy Project?
-
Focus on writing and not on workflow.
-
Involve peer-reviews, SMEs and end users.
-
Easy start for first-time contributors.
-
Easier produce deliverables and correct errors in older deliverables.
-
Allow for future evolution: more writers, more outputs, more content, more
products.
Why do big companies use the DITA standard?
-
Standard means owning your content and no vendor lock-in (editing or
publishing). -
DITA works very well with topic-based authoring.
-
Lots of content reuse potential.
-
Reuse lowers translation costs.
DITA Doc Project Aspects
Storage
-
Commercial content management systems (CMS).
-
Open Source version control systems: Git, Subversion, CVS
Version Control
Working with the storage system
-
Commercial CMSs – Remote editing, locking.
-
Open Source version control systems – Local working copies, no editing
restrictions → conflicts.Hint: Maybe you can use the same storage system as software developers in
your company.
Collaboration and Workflow
Workflow
Issue tracking
-
Using workflow features in the CMS
-
Using issue management systems like Bugzilla, Atlassian JIRA or Trello.
- Tip: Linking the product development with the documentation
development.
- Tip: Linking the product development with the documentation
Issue Tracking Examples
Custom workflows
Issue tracking – Simple Documentation Workflow
Issue tracking – Development and Documentation Workflow
Issue Tracking and Storage Integration
Issue Tracker can provide a single place where you can monitor a ticket from start to
end, including:
Issue description and details
-
Who worked on that issue
-
What was changed in the application
-
What was changed in the documentation
-
Who should be notified when issue is resolved.
Involving Subject Matter Experts
How can end users collaborate with us?
-
Send feedback via email/forum/phone.
-
Send feedback in the published HTML output.
-
Give feedback using an online DITA editing tool with comment-only capabilities.
Contribution Consistency
Sharing common settings between writers
-
Custom style guide.
-
Specific editing enhancements.
-
Specific validation settings.
-
Controlled attribute values.
-
Custom spell and auto-correct dictionaries.
-
Various other common preferences.
Custom Style Guide
The style guide is internal documentation about how to write documentation.
How can we remember what’s written in the style guide?
Automating Style Guide Rules
Schematron Checks to help Technical Writing
Using the same terminology rules
Checking Terminology with Oxygen XML Editor
-
Custom Spell dictionaries.
-
Custom auto-correct mappings.
-
Advanced terminology checkers like Acrolinx, HyperSTE or LanguageTools.
-
Building your own terminology checker using Schematron.
DITA Project Structure
File and folder naming/organization conventions
Managing Content Reuse
DITA Reuse Strategies
-
Separate folders containing reusable content.
-
Keep dictionaries of reusable components
-
Prefer indirect references (conkeyrefs)
Managing Links
DITA Linking Strategies
Project-wide refactor operations
-
Convert between various topic types.
-
Rename or move one or more topics.
-
Change XML structure in topics from the entire project.
- Example: Change the value of a specific attribute.
Translation
Translating your DITA Project
-
You create your content in the primary language using a DITA authoring tool .
-
Send a copy of the relevant DITA files to the localization service provider
(LSP). -
Receive translated DITA content back from (LSP).
Optimizing for translation
Publishing
-
Validate each topic according to DITA standard.
-
Check for broken links, key references and content references, missing images or
referenced resources. -
Check for broken links to remote web sites.
-
Check for broken links in the context of profiling filters.
Producing the deliverables
-
Checking the project before publishing.
-
Sharing publishing customizations
-
Automatic production of deliverables either via CMS or via an automated open
source server (Jenkins).
Useful links
Conclusions
A healthy DITA project needs to:
-
Be Manageable.
-
Allow for scalability.
-
Allow for easy collaboration.
-
Allow for detection and correction of mistakes before the deliverables are
published. -
Allow for correction of mistakes after the deliverables are published.
But don’t panic if you do not have all the aspects of a project covered, your project does
not need to be perfect, it needs to be perfectible.
- Affordable SEO Powered Toolkit. RankFaster Today.
- Echobase.AI. Easily Integrate AI into your business. Access Here.
- EliteSocialHUB. Media Strategy. Social Management tools. Access Here.
- Next-Gen Intelligent Tools. AICryptoPredictions, WriteCraftAI, AIQuickTasks, BlockChain, Articles, Blog. Access Here.
- CoreFlowIntelligence.AI. Leaders in AI Consulting and Solutions. Contact US Here.
