Agile Meets DITA: Developing User Documentation in an Agile Environment
1 like561 views
The document discusses how writers can develop user documentation in an agile environment using DITA (Darwin Information Typing Architecture). Some key points: - Agile development focuses on iterative delivery in short cycles called sprints, requiring documentation to also be produced incrementally. - DITA is a standard for authoring reusable topic-based content that can be more easily updated and assembled incrementally to match iterative development. - When using DITA, writers can translate user stories into task-based documentation, take a minimalistic approach, and focus on producing "fit for purpose" documentation.
Agile Meets DITA: Developing User Documentation in an Agile Environment
- 1. Agile Meets DITA: Developing User Documentation in an Agile Environment Nabayan Roy AutoCAD Learning Experience
- 2. The Advent of Agile • Both a philosophy and a method • Set of processes for development • Help create better software, faster
- 3. The Paradigm Shifting Tenets for Writers • The two tenets are: Bottom line is that there are no prescriptions for documentation.
- 4. What Has Changed For A Writer? Functional specs are secondary Estimate developer and QA effort for documentation in a sprint Implement 80/20 rule Test features in developer builds Delegation of work within team Speak Up! Make others understand why it would take so much time to document a feature
- 5. The Key Challenges For Writers Incremental releases, multiple scrums Incremental releases, multiple scrums Incremental development versus incremental documentation Ability to rewrite & assemble, anytime
- 6. A Genie called Darwin Information Typing Architecture (DITA) • DITA is an OASIS standard XML data model for authoring and publishing. • Created at IBM • Cost-effective way to create, publish, reuse, and exchange structured content
- 7. Defining DITA For You Darwin Information Typing ArchitectureDITA utilizes principles of inheritance for specialization DITA was designed for technical information based on a concept, task and reference architecture DITA is a model for extension – both of design and processes Darwin Information Typing Architecture
- 8. The Heart of DITA: Information Types • DITA is more of an information type than a document type • DITA has three types of base topics Topic Task Reference Concept
- 9. Key Design Principles of DITA
- 10. How does DITA Help Writers Thrive in a Scrum Team? • Topic-oriented approach • Leveraging user stories to produce task-based documentation • Applying the principles of minimalism • ‘Fit to purpose’ documentation
- 11. Topic-oriented Approach • DITA organizes content into topic-based information units, with each topic describing a task, concept, or reference. Update and replace topics of information as needed Receive increased consistency Cohesive, self- contained, re-usable elements Receive a quicker time to value
- 12. Translating User Stories into Task- based Documentation User-centric Modular documentation Measurable Relevant Task-based writing
- 13. Minimalistic Approach • Minimalism is one of the key elements of DITA • Keep It Straight & Simple (KISS) and Keep It Light (KIL) • Keep documentation action- oriented
- 14. ‘Fit To Purpose’ Documentation • Visualize content and tasks that are granular and can be reused. • Reusability flows from the topic-based paradigm in DITA • Map architecture guides the assembling for incremental documentation (bottom line implementation) keeping in mind the final documentation deliverable (top-down design)
- 15. Incremental Documentation • Great documentation is a continuous effort, which evolves based on feedback on a continuous basis. • Documentation, as development, is an iterative process. Leverage DITA to write your perfect document. • DITA supports continuous publishing, which is any-time, any-format, and any-media.
- 16. How it All Fits Together The Complete User Story for Creating a Web Store Front Integrated View Creating the database catalog Managing the system Designing the system Messaging notifications Task Stories in a Sprint Serving the catalog to customers
- 17. Best Practices for An Agile Writer Hold Planning Iterations Have ‘Pair- Writers’ Develop documentation design patterns
- 18. Best Practices for An Agile Writer Be Involved, Speak Up, and Be Agile Use tools that work for you
- 19. Engagement City
- 20. References Articles • C.Sigman, Adapting Challenges and Strategies to Scrum, Intercom magazine Jul-Aug 2007 • T.Berry , A.Gentle, Writing End-User Documentation in an Agile Environment, CIDM, Jun 2006 • A.Fox, M.Kramer, Mobile and Agile: The Floating Writer's Survival Kit , WritersUA 2008 • Scott Nesbitt, An Introduction to DITA, InformIT, Oct 2006 • Chris Benz, What is DITA and Why Should You Care?, LearnCon, Sept 2010 Books • Agile Estimating and Planning, by Mike Cohn • Agile Documentation, Andreas Ruping • User Stories Applied for Agile Software Development ,by Mike Cohn • DITA Best Practices: A Roadmap for Writing, Editing, and Architecting in DITA, by Laura Bellamy Video • SDLonline Images • www.flickr.com