Agile Content Development and the IXIASOFT DITA CMS
Download as PPTX, PDF•2 likes•1,524 views
The document discusses the integration of agile methodologies with the DITA content management system, highlighting the importance of agile development in technical documentation. It includes insights from several panelists on their experiences and best practices for implementing agile within documentation teams, emphasizing the need for collaboration, rapid feedback, and adaptability to changing customer needs. The document also outlines challenges faced by technical writers in agile environments and the advantages of using DITA for content reuse and structured documentation processes.
![• Content reuse: “write once,
use many”
No need to re-write what
already exists
Content consistency
Single-sourcing is built in
Agile and Content Reuse in DITA
“[DITA] handles the reuse of small information chunks brilliantly. My
engineers reused functions and objects constantly as they developed new
features. I found it invaluable to be able to conref (reuse by reference)
previously written tables, sections, paragraphs, procedure steps, etc..
During that last long night at the end of sprint I was never too proud to
reuse available writing.”
– Stan Doherty](https://image.slidesharecdn.com/agileandditacmsfinal-151015185808-lva1-app6892/85/Agile-Content-Development-and-the-IXIASOFT-DITA-CMS-20-320.jpg)
Agile Content Development and the IXIASOFT DITA CMS
- 1. Agile Content Development and The IXIASOFT DITA CMS
- 2. Agenda •Introductions •Overview of Agile + DITA •Questions for panel •Panel & audience discussion
- 3. The Panelists Ed Owen Senior Manager of Information Development Infrastructure at Wind River Provide tech support to the writing teams using the CMS Provide on-going enhancements and fixes to the CMS system and output transforms Uses agile for own team and supports CMS used by info development teams that also Agile Catherine McNair Senior Technical Writer at Agfa HealthCare, IITS group (three different project teams, two of which are remote) Sits with writers and not project teams Used Scrum Agile as product owner and scrum master to support the conversion from our old, specialized CMS to Ixiasoft Maxine Pike Principal Information Developer at Infor, Global Documentation Team Leads a team that uses Agile to implement procedures and standards for automated publishing from the CMS Her team tracks tasks in Atlassian JIRA, using a Scrum board. She serves as ScrumMaster
- 4. About Jason
- 5. Who’s This Guy? • Keith Schengili-Roberts • DITA Information Architect with IXIASOFT Supports DITA CMS Member on OASIS DITA Adoption and Technical Committees • Also the guy behind the DITAWriter.com website • Formerly Tech Docs Manager at AMD • Have been using DITA for 10+ years
- 6. What is “Agile” development? • Create products based on a prioritized list of customer needs (Story: “I need to be able to do…”)
- 7. Agile in Technical Documentation • Have been asking clients recently if they are Agile. Almost invariably they say “yes”. • But when I ask them about their processes they are often in fact: Waterfall-based, or “Rest of company is Agile so we must be too”, or Transitioning to some flavor of Agile. Few are fully Agile
- 8. Waterfall Management and Technical Writing • The waterfall model began in the software development realm in early 1970s • Sequential design process, starting with analysis and ending with maintenance (updates) • Technical writing typically fell between Coding and Testing phases, well after Requirements and Design phases • “Just document what’s there (or will be there).”
- 9. Problems with Waterfall Management Waterfall-based software projects were prone to failure • In 1995 DoD found that of $35.7 billion spent by the organization on software, only 2 percent of the software was usable as delivered, and that 75% was either never used or was cancelled prior to delivery. • Waterfall does not deal with changing/adapting to customer needs gracefully
- 10. Development of Agile • Agile Manifesto written in 2001, advocated: Releasing early and often Build code daily, iterate on changes quickly Embed skilled teams • Many “flavors” of Agile have been developed since then, but the basic tenants still hold true • For technical writers this meant: Work more closely with developers Provide early feedback on product Constant change/iterations of content
- 11. ISO standard for Agile Documentation • ISO/IEC/IEEE 26515:2011- 12 is an ISO standard describing how to develop user documentation in an Agile environment • Neatly outlines everything you need to know about Agile + documentation • Dates to 2012, and there is currently a drive to update it
- 12. “Flavors” of Agile • There are many different techniques and approaches that are Agile or allied with Agile • They include (but are not limited to): Scrum Kanban eXtreme Programming (XP) Lean
- 13. Scrum and Kanban • Focuses on emerging requirements and responding quickly to change • Includes daily meetings held by Scrum Master, plan Sprints for work to be done in a short timeframe • Review what team members have done, what they will do and whether there are impediments to progress • Card-based “Just in Time” methodology originally used by manufacturers (Toyota) • Kanban team focuses on work in progress; when done, pulls next card from top of backlog • A goal is to optimize start to finish cycle time, teams make themselves and their work more efficient Standup Scrum Meeting Kanban Board
- 14. eXtreme Programming (XP) and Lean • Activities: coding, testing, listening, designing • Assume simplicity, embrace change, rapid feedback • Multiple short development cycles, emphasis on feedback on code (unit tests) and customer (acceptance tests); this includes documentation • Seeks to eliminate things that do not add value to customer (“muda”, a type of waste) • Continuous improvement, short iteration cycles, deliver as fast as possible
- 15. Agile Implications for Documentation Processes • Content creators have to work more closely with developers • Documentation may support broader communication, such as between teams, customers, audit process, etc. • Work cycles are faster, feedback more critical • Efficient documentation tools make things easier (single sourcing, structured content, CMS)
- 17. What’s Your Role? Is Your Content Considered Part of the Product? Pigs produce product: Scrum master, programmers, scrum team, product owner (if committed) Chickens are involved, engaged & interested Users, stakeholders (includes management, business owners (accountable)), consulting experts Which are you?
- 18. Are You Part of the Team? • In Agile, content creators often start as chickens… • What can you do to be accepted as part of the team?
- 19. DITA is Clearly Popular Among Agile Teams • DITA is the most popular form of structured content used by Agile teams (data from LinkedIn): 0 10 20 30 40 50 60 DITA XML + Agile vs. DITA XML Alone DocBook + Agile vs. DocBook Alone SGML + Agile vs. SGML Alone S1000D + Agile vs. S1000D Alone FrameMaker + Agile vs. FrameMaker Alone Overall Percentage of Users with Agile Experience per Specification/Tool
- 20. • Content reuse: “write once, use many” No need to re-write what already exists Content consistency Single-sourcing is built in Agile and Content Reuse in DITA “[DITA] handles the reuse of small information chunks brilliantly. My engineers reused functions and objects constantly as they developed new features. I found it invaluable to be able to conref (reuse by reference) previously written tables, sections, paragraphs, procedure steps, etc.. During that last long night at the end of sprint I was never too proud to reuse available writing.” – Stan Doherty
- 21. A DITA Advantage: Separation of Form and Content • Time is spent writing rather than formatting Separating content from formatting saves considerable time In an informal survey done on a team of technical writers using popular DTP software, roughly half of their time was spent formatting content. That time can now instead be put towards writing more Agile content in a structured XML environment
- 22. User Stories and DITA Tasks • Scrum-based Agile often calls upon User Stories to craft development • Often take form of various procedures that users will want to accomplish; this fits DITA’s topic types nicely “DITA allows correlating user stories to specific procedures much easier than other less granular formats. This can be utilized in some pretty creative ways to apply principals of continuous integration, and testing to documentation.” - Casey Jordan
- 23. User Stories and DITA Tasks (cont.) • Agile Best Practice for writing tasks: Instead of writing a concept to be followed by a task, encapsulate that concept as the context for a task instead Depending on scenario, describe expected outcomes for individual steps/conclusion Use concept topics to link between tasks Concept Task Task Context
- 24. Short Descriptions Helps Direct Users to Content • Writing short description for DITA topics is already considered a best practice Arguably more so for Agile- based content, as it provides a means of progressive disclosure as to the relevancy of content to users Can be similar in intent to a user story: “User x can do y based on z”
- 25. DITA 1.3 Troubleshooting and Agile • DITA 1.3 adds troubleshooting as a new topic type • Designed to provide specific solutions to scenarios that are likely to arise, and how to solve them • Will be welcomed by Agile writers who are looking for a trouble-shooting option for user stories and where a task may not be an appropriate solution “The troubleshooting pattern of condition > cause > remedy is essentially a scenario.” - Bob Thomas
- 26. DITA Topic Granularity and Measurability • DITA’s topic-based approach also makes it easy to measure content Within a CMS it is also possible to track how “done” topics within a map are • DTP-based docs much harder to track due to lack of this level of granularity “Our project managers could track progress of documentation deliverables within our DITA-based CMS on a daily basis.” - Jason Owen
- 27. Feedback is Part of Agile • Documentation feedback is a developer requirement under Agile • Using DITA, turnaround of topic-based review with SMEs much reduced SMEs can provide feedback in a more timely manner “Developers would review topics on the spot in the Agile team room. Agile also left no room for procrastination, so this was an easy way for them to check this off their own task list.” - Jason Owen
- 28. Common Problems Encountered by Tech Doc Teams Problem #1: Agile will not solve understaffed tech doc teams Symptoms: • Writers cannot attend stand- up meetings due to scheduling conflicts • Writers perennially falling behind on assigned topics to write A good Agile process manager will recognize the problem and either throttle back work or bolster effort for new hires
- 29. Common Problems Encountered by Tech Doc Teams Problem #2: Need to make documentation “glue” for publications Applies to cases where a full manual is expected High-level introductory or conceptual material not typically accounted for in a sprint There’s still a need to answer the “why would you use this?” type of question Solution is to recognize this need up front, and allow for it in the overall documentation plan
- 30. Some Parting Thoughts “DITA did not directly enable or guarantee effective documentation in an Agile/SCRUM environment, but it sure saved my bacon in supporting multiple scrum teams with variant definitions of done.” - Stan Doherty “Agile development goes hand in hand with topic writing, and I think this is why it’s a perfect match for DITA. I love working in Agile! It makes my life as a writer much, much easier.” - Nathalie Laroche
Editor's Notes
- #4: Ed - Job title: Senior Manager of Information Development Infrastructure - The group you work for in your company: Information Development - Agile experience: - Wind River has been using Agile company-wide for product development for the past 2-3 years - My direct experience with formal Agile for this product development has been minimal, but our writing teams have been working in it for that time - I do use lowercase-a “agile” methods for my internal tools team; we track our work in sprints and release our tools and systems every three weeks - Describe your role and responsibilities for the CMS and Agile - My infrastructure team chose, installed, and deployed the DITA CMS - We provide tech support to the writing teams using the CMS - We provide on-going enhancements and fixes to the CMS system and output transforms - We play no role in Agile per se at Wind River - Describe your organization’s Agile methodology - Scrum / Rally - Wide variation in specific Agile practice and methods across development teams - Content development managers use Rally to represent their documentation tasks as part of the overall project - Writers may work religiously in Rally, or may not - Writers typically do not attend all scrum meetings, if any; at most, once a week - Writers located with other Agile team members is the exception more than the rule Catherine I am Senior Technical Writer at Agfa HealthCare. I work in the IITS group, on three different project teams. All of them develop different types of medical software, variously used by database, system, and PACS administrators; radiologist, clinicians, technologists, and medical secretaries; and internal service personnel. And all of the teams use some form of Scrum Agile methodology to get their work done. Some have been using it for years; others started only 2-3 years ago. In no case am I a fully integrated Scrum member. I don’t sit with any of those teams, but with the rest of the writers. Two of my teams are largely remote, one in Shanghai, so with them I don’t participate in any planning, demo, or standup meetings. With the local one, I do go to the sprint planning and review / demo meetings, but not the standups. With the local one, I sometimes get assigned tasks, but I’m never part of the velocity measurement. I have no Agile certification; just some training and reading. Still, one the most effective ways I deployed scrum methodologies personally at work was to act as product owner and often scrum master (I know the same person isn’t supposed to do both) to get the whole documentation team working through the many tasks we had to do to support the conversion from our old, specialized CMS to Ixiasoft. Maxine Uses Agile to manage information architecture and publishing work with the DITA CMS. Job title: Principal Information Developer The group you work for in your company: Global Documentation Team Agile experience (years of experience, certifications, etc.): I am a complete newbie to Agile, just started using Agile methodology about six months ago Describe your role and responsibilities for the CMS and Agile: Here’s the bio I sent to Leah today: Maxine is a Principal Information Developer and information architect at Infor. She has worked for the company for almost 20 years in a variety of roles within the global documentation team. In her current role, she is responsible for leading a virtual team to implement procedures and standards for generating output and automating delivery from Infor's implementation of the IXIASOFT DITA CMS. She is also overall Project Definition Administrator in the DITA CMS with responsibility for making sure the team defines products, releases, and versions in the DRM module according to Infor standards. She has started using Agile for planning the automated publishing work with the CMS. They track tasks in Atlassian JIRA, using a Scrum board. She serves as ScrumMaster.
- #8: People do not want to be perceived as not being Agile (even if they do not fully know what that is) The other people on this panel have considerable experience with Agile within a documentation team
- #10: References: http://www.techrepublic.com/blog/tech-decision-maker/the-roots-of-agile-project-management/
- #22: I have seem some arguments that adding tags takes “extra keystrokes”, but the fact is that you don’t have to change your tags once they are in place, whereas you will likely have to do that with things like header content in a typical DTP program
- #25: Example is from Ixiasoft’s own online DITA CMS documentation
- #26: This can be countered by saying that good Agile software development should not require troubleshooting; I believe however that there will always be circumstances where troubleshooting will always be necessary, or post-launch scenarios arise that were not thought of while creating User Stories in the original development process
- #27: Quote is from an interview I did with Jason Owen from his Agile experience at TruePosition
- #29: In one of the interviews I did there was a tech docs team that started to do Agile along with its development teams, but found it could not cope, due to a combination of poor scheduling (writers couldn’t always be there for the all-important scrum meetings) and were arguably understaffing. In the end the tech doc team reverted to Waterfall style management—in other words: “give us the program when it is done and we will document it”—to be able to cope. A good Agile deployment will include documentation teams and other stakeholders outside of the development team.
- #30: This example came from Nathalie Laroche from her experiences with two different Agile teams