dita and agile are made for each other
TRANSCRIPT
![Page 1: DITA and Agile Are Made For Each Other](https://reader035.vdocuments.mx/reader035/viewer/2022062823/586fc6e31a28aba24c8b5e85/html5/thumbnails/1.jpg)
DITA and Agile are Made for Each Other
Keith Schengili-RobertsDITA Information Architect, IXIASOFT
![Page 2: DITA and Agile Are Made For Each Other](https://reader035.vdocuments.mx/reader035/viewer/2022062823/586fc6e31a28aba24c8b5e85/html5/thumbnails/2.jpg)
Agenda
• Introduction• Documentation Management
History / Beginnings Waterfall and Agile Flavors of Agile
• DITA and Agile Popularity and growth of DITA and Agile How DITA Helps Technical Writers Working in an Agile
Environment Specific examples / Case studies
• Q/A
![Page 3: DITA and Agile Are Made For Each Other](https://reader035.vdocuments.mx/reader035/viewer/2022062823/586fc6e31a28aba24c8b5e85/html5/thumbnails/3.jpg)
Who’s This Guy?
• Keith Schengili-RobertsWhat I do: • DITA evangelist• Liaison with OASIS; on DITA
Adoption and Technical Committees, also aiding in relaunch of dita.xml.org website
• Industry researcher• Also lecturer on Information
Architecture at the University of Toronto
• Have 10+ Years of experience with DITA XML
![Page 4: DITA and Agile Are Made For Each Other](https://reader035.vdocuments.mx/reader035/viewer/2022062823/586fc6e31a28aba24c8b5e85/html5/thumbnails/4.jpg)
Am Also “DITAWriter”
• Industry blog started ~5 years ago• Just over 195,000 hits• Have regularly updated info on
DITA Conferences, DITA Books, DITA CMSes, DITA Editors, other DITA Tools, and DITA Consulting Firms
• Recent updated “Companies Using DITA” listing, now with over 600 firms
• News and views on DITA use • Also features interviews with
those making a difference in the world of DITA
![Page 5: DITA and Agile Are Made For Each Other](https://reader035.vdocuments.mx/reader035/viewer/2022062823/586fc6e31a28aba24c8b5e85/html5/thumbnails/5.jpg)
Another Thing People Might Not Know About Me…
• I have always had an interest in Management studies and hold a Masters in Public Administration (MPA) Have been exposed to many
management trends over the years, and teach Lean techniques in my IA course
Am particularly interested in effective management of documentation groups
• Since summer 2015 have been interviewing various techwriters and managers about their Agile + DITA experiences
![Page 6: DITA and Agile Are Made For Each Other](https://reader035.vdocuments.mx/reader035/viewer/2022062823/586fc6e31a28aba24c8b5e85/html5/thumbnails/6.jpg)
Beginnings of Technical Writing
• There has always been a need to instruct people on how to do practical things, including: Ancient Egyptian medical and
mathematical texts Certain Ancient Greek
philosophical works Roman engineering texts Medieval instructional
publications • In English, the first instruction
manual is widely considered to be Chaucer’s “A Treatise on the Astrolabe”
![Page 7: DITA and Agile Are Made For Each Other](https://reader035.vdocuments.mx/reader035/viewer/2022062823/586fc6e31a28aba24c8b5e85/html5/thumbnails/7.jpg)
Technical Writing as a Cottage Industry
• Technical writing as we know it started in early 20th century Ford Model T manual (1919) is a
good example of this Joseph Chapline wrote first
computer manual for BINAC (1949)• Was often done by a single person,
often a SME• They tended to idiosyncratic and
often one-offs• Thinking was that you didn’t need to
“manage” a single person writing content
![Page 8: DITA and Agile Are Made For Each Other](https://reader035.vdocuments.mx/reader035/viewer/2022062823/586fc6e31a28aba24c8b5e85/html5/thumbnails/8.jpg)
Technical Writing and DTP• Growth of technical writing developed
(primarily) alongside growth of software industry
• Desktop Publication Programs made it possible to writers to create documents from beginning to end This also opened up possibilities for
collaboration• Initial attempts were awkward, often
involved sneaker-net (passing a floppy disc with content to another writer) Basically one isolated writer
handing content over to another
![Page 9: DITA and Agile Are Made For Each Other](https://reader035.vdocuments.mx/reader035/viewer/2022062823/586fc6e31a28aba24c8b5e85/html5/thumbnails/9.jpg)
The Need for Documentation Management
• As volume of content grew, collaborative documentation practices became a necessity No longer one writer=one
document, but many writers=one document / many documents
• Getting writers to collaborate has been described as being akin to “cat herding”
![Page 10: DITA and Agile Are Made For Each Other](https://reader035.vdocuments.mx/reader035/viewer/2022062823/586fc6e31a28aba24c8b5e85/html5/thumbnails/10.jpg)
Focus on Managing Documentation Processes
• As documentation teams grew, was a real need to coordinate tech writing projects
• JoAnn Hackos’ Information Development (2006) was the first book to explore subject of documentation management And the book does talk about Agile:
“It is most important for information project managers to recognize that traditional project management methods must be adapted to agile projects. It may be impossible, for example, to produce traditional documentation at all.” (pg. 342)
![Page 11: DITA and Agile Are Made For Each Other](https://reader035.vdocuments.mx/reader035/viewer/2022062823/586fc6e31a28aba24c8b5e85/html5/thumbnails/11.jpg)
Waterfall Management and Technical Writing
• The waterfall model also began in the software development realm, first described in detail 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).” Majority of documentation teams out
there still follow this model (and there’s nothing necessarily wrong with that)
A certain young tech writer at Delrina, circa mid-1990sPre-Agile, definitely Waterfall
![Page 12: DITA and Agile Are Made For Each Other](https://reader035.vdocuments.mx/reader035/viewer/2022062823/586fc6e31a28aba24c8b5e85/html5/thumbnails/12.jpg)
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
![Page 13: DITA and Agile Are Made For Each Other](https://reader035.vdocuments.mx/reader035/viewer/2022062823/586fc6e31a28aba24c8b5e85/html5/thumbnails/13.jpg)
Agile is Not for Every Business Environment
• Agile thrives in environments where short release cycles are possible; appears to be rare in highly regulated environments or heavy machinery for example Have found one case of Agile being used in Pharma, though only
after and their software division successfully adopted it I have found instances of Agile + DITA in Medical Devices, Heavy
Machinery sectors, but in these cases it was by the software divisions at these firms
• In environments where business factors are pushing for rapid change in product development, Agile methodologies are likely to be introduced
![Page 14: DITA and Agile Are Made For Each Other](https://reader035.vdocuments.mx/reader035/viewer/2022062823/586fc6e31a28aba24c8b5e85/html5/thumbnails/14.jpg)
Where Agile Thrives
• In general, software is in the shaping quadrant of industry types, where environment is unpredictable but can be “shaped”• Rapid testing of releasable
product helps shape the market/user’s expectations; Agile approach makes this possible• Need an equally “agile” way to
manage documentation
![Page 15: DITA and Agile Are Made For Each Other](https://reader035.vdocuments.mx/reader035/viewer/2022062823/586fc6e31a28aba24c8b5e85/html5/thumbnails/15.jpg)
Evolution of DITA within Technical Writing
• DITA is arguably the natural evolution of the need for many writers to work and reuse content more efficiently
• Similarly, Agile can be seen as a way for fast-moving development teams to meet the needs of their customers The two methodologies
compliment each other (when done right)
![Page 16: DITA and Agile Are Made For Each Other](https://reader035.vdocuments.mx/reader035/viewer/2022062823/586fc6e31a28aba24c8b5e85/html5/thumbnails/16.jpg)
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 a drive to update it
![Page 17: DITA and Agile Are Made For Each Other](https://reader035.vdocuments.mx/reader035/viewer/2022062823/586fc6e31a28aba24c8b5e85/html5/thumbnails/17.jpg)
Similarities Between Agile and DITA Sectors• Though not a direct correspondence, there is at least some
cross-over between DITA- and Agile-using firms
Source: DITAWriter.com Source: VersionOne 10th Annual State of Agile Report. © 2016 VersionOne Inc. All rights reserved.
![Page 18: DITA and Agile Are Made For Each Other](https://reader035.vdocuments.mx/reader035/viewer/2022062823/586fc6e31a28aba24c8b5e85/html5/thumbnails/18.jpg)
DITA is Clearly Popular Among Agile Teams
• DITA is the most popular form of structured content used by Agile teams (data from LinkedIn):
![Page 19: DITA and Agile Are Made For Each Other](https://reader035.vdocuments.mx/reader035/viewer/2022062823/586fc6e31a28aba24c8b5e85/html5/thumbnails/19.jpg)
Development of Agile
• Agile Manifesto written in 2001:
• A clear difference from the traditional waterfall approach to docs
![Page 20: DITA and Agile Are Made For Each Other](https://reader035.vdocuments.mx/reader035/viewer/2022062823/586fc6e31a28aba24c8b5e85/html5/thumbnails/20.jpg)
There Are Many “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
![Page 21: DITA and Agile Are Made For Each Other](https://reader035.vdocuments.mx/reader035/viewer/2022062823/586fc6e31a28aba24c8b5e85/html5/thumbnails/21.jpg)
Scrum and Kanban
Scrum:• 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
Kanban:• 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
![Page 22: DITA and Agile Are Made For Each Other](https://reader035.vdocuments.mx/reader035/viewer/2022062823/586fc6e31a28aba24c8b5e85/html5/thumbnails/22.jpg)
eXtreme Programming and Lean
eXtreme Programming (XP):• 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
Lean:• 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
![Page 23: DITA and Agile Are Made For Each Other](https://reader035.vdocuments.mx/reader035/viewer/2022062823/586fc6e31a28aba24c8b5e85/html5/thumbnails/23.jpg)
Which Agile Methodologies are Used the Most?
• While Scrum is clearly dominant, hybrid approaches are also common
Source: VersionOne 10th Annual State of Agile Report. © 2016 VersionOne Inc. All rights reserved.
![Page 24: DITA and Agile Are Made For Each Other](https://reader035.vdocuments.mx/reader035/viewer/2022062823/586fc6e31a28aba24c8b5e85/html5/thumbnails/24.jpg)
Agile in Technical Documentation
• I have been interviewing tech doc members at various companies who said they were Agile.
• But when I ask them about their processes they are often in fact: Largely Waterfall-based, or Do not want to be perceived as not
being Agile (whatever that is), or “Rest of company is Agile so we must
be too” (i.e. “Agile by osmosis”), or Transitioning to some flavor of Agile.
• I found “pseudo-Agile” doc teams to be surprisingly common.
![Page 25: DITA and Agile Are Made For Each Other](https://reader035.vdocuments.mx/reader035/viewer/2022062823/586fc6e31a28aba24c8b5e85/html5/thumbnails/25.jpg)
Why DITA + Agile = A Great Partnership!
DITA AgileTopic-based approach Incremental development; can update
topics as required; self-containedTask topics User stories; content is focused
squarely on what user needs to doIndividual topics can be counted; in a CMS workflow can be measured
Need to track development progress; easy to demonstrate progress
Best practice of minimalism Document only what needs to be documented; Keep It Straight and Simple (KISS) and Keep It Light (KIL); Reduces waste
Reuse improves content consistency Continuous feedback from developers and users
Iterative publication to multiple formats on demand
No holdup for incremental product releases
![Page 26: DITA and Agile Are Made For Each Other](https://reader035.vdocuments.mx/reader035/viewer/2022062823/586fc6e31a28aba24c8b5e85/html5/thumbnails/26.jpg)
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)
Following slides examine some common approaches I ran across various DITA + Agile teams
![Page 27: DITA and Agile Are Made For Each Other](https://reader035.vdocuments.mx/reader035/viewer/2022062823/586fc6e31a28aba24c8b5e85/html5/thumbnails/27.jpg)
What Agile Means in Practice for Tech Doc Teams
• Work more closely with developers Tech writer assigned to work with one or more
development teams; does regular reports on progress (Scrum with Stand-up meetings, Kanban priorities, etc.)
• Provide early feedback on product Through active use of product tech writers often become
advocate for users; helps to define realistic user stories• Constant change/iterations of content
Incremental releases, and a change of focus from “document everything” to “document only what the user needs”
![Page 28: DITA and Agile Are Made For Each Other](https://reader035.vdocuments.mx/reader035/viewer/2022062823/586fc6e31a28aba24c8b5e85/html5/thumbnails/28.jpg)
• 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
![Page 29: DITA and Agile Are Made For Each Other](https://reader035.vdocuments.mx/reader035/viewer/2022062823/586fc6e31a28aba24c8b5e85/html5/thumbnails/29.jpg)
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 usingpopular DTP software, roughly half of their time was spentformatting content. That time can now instead be put towards writing more Agile content in a structured XML environment
![Page 30: DITA and Agile Are Made For Each Other](https://reader035.vdocuments.mx/reader035/viewer/2022062823/586fc6e31a28aba24c8b5e85/html5/thumbnails/30.jpg)
Tech Writers Become Part of Feedback Loop
• Tight integration of tech writers with development team opens possibilities for early feedback on product development
“The goal of technical communicators is not to explain confusing product features, but to prevent them.” – Tim Grantham, 2008
![Page 31: DITA and Agile Are Made For Each Other](https://reader035.vdocuments.mx/reader035/viewer/2022062823/586fc6e31a28aba24c8b5e85/html5/thumbnails/31.jpg)
Separate Content Management from Authoring
• Ideally IA / Manager are several iterations ahead and planning out topics to be authored Map with topics created, writers “fill in the blanks” Helps to emphasize that writers need to be embedded
with development + QA
Example of creating stub topics within a map in the IXIASOFT DITA CMS
![Page 32: DITA and Agile Are Made For Each Other](https://reader035.vdocuments.mx/reader035/viewer/2022062823/586fc6e31a28aba24c8b5e85/html5/thumbnails/32.jpg)
Only Document What is Necessary
• Not only based on feedback from developers, but also from users
• Fits with minimalist writing principles; ditto Lean• When possible, track online usage from published
docs, and prioritize user-favored content One interesting example: UI-related content “how to”
style content is reduced and UX is improved by writer feedback, ensuring UI is more usable
![Page 33: DITA and Agile Are Made For Each Other](https://reader035.vdocuments.mx/reader035/viewer/2022062823/586fc6e31a28aba24c8b5e85/html5/thumbnails/33.jpg)
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
![Page 34: DITA and Agile Are Made For Each Other](https://reader035.vdocuments.mx/reader035/viewer/2022062823/586fc6e31a28aba24c8b5e85/html5/thumbnails/34.jpg)
User Stories and DITA Tasks (cont.)
• Possible 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
![Page 35: DITA and Agile Are Made For Each Other](https://reader035.vdocuments.mx/reader035/viewer/2022062823/586fc6e31a28aba24c8b5e85/html5/thumbnails/35.jpg)
Epics and Audiences
• “Epics” are a collection of related user stories that comprise the complete workflow for a type of user
• From a DITA standpoint, epics can be used to help refine conditional processing for audience User types may change during development; the “agility”
and flexibility of DITA makes it possible to change quickly
![Page 36: DITA and Agile Are Made For Each Other](https://reader035.vdocuments.mx/reader035/viewer/2022062823/586fc6e31a28aba24c8b5e85/html5/thumbnails/36.jpg)
Short Descriptions 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”
![Page 37: DITA and Agile Are Made For Each Other](https://reader035.vdocuments.mx/reader035/viewer/2022062823/586fc6e31a28aba24c8b5e85/html5/thumbnails/37.jpg)
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 troubleshooting 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
![Page 38: DITA and Agile Are Made For Each Other](https://reader035.vdocuments.mx/reader035/viewer/2022062823/586fc6e31a28aba24c8b5e85/html5/thumbnails/38.jpg)
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
![Page 39: DITA and Agile Are Made For Each Other](https://reader035.vdocuments.mx/reader035/viewer/2022062823/586fc6e31a28aba24c8b5e85/html5/thumbnails/39.jpg)
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
![Page 40: DITA and Agile Are Made For Each Other](https://reader035.vdocuments.mx/reader035/viewer/2022062823/586fc6e31a28aba24c8b5e85/html5/thumbnails/40.jpg)
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
![Page 41: DITA and Agile Are Made For Each Other](https://reader035.vdocuments.mx/reader035/viewer/2022062823/586fc6e31a28aba24c8b5e85/html5/thumbnails/41.jpg)
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
![Page 42: DITA and Agile Are Made For Each Other](https://reader035.vdocuments.mx/reader035/viewer/2022062823/586fc6e31a28aba24c8b5e85/html5/thumbnails/42.jpg)
An Example of How DITA Can Enable Agile
Lean methodology employed at AMD; early on localization was a focus:• Under old toolchain could only
localize software (with 1 month cadence) once every 6 months
• Using DTP-based processes, it was costly, slow and process did not allow for feedback
DITA + CMS made localizing on a monthly cadence possible• Demonstrated considerable costs
savings• Localization staff could focus on
quality and provide developers with feedback
Localization Process Pre-Lean:
Localization Process After Lean + DITA + CMS:
![Page 43: DITA and Agile Are Made For Each Other](https://reader035.vdocuments.mx/reader035/viewer/2022062823/586fc6e31a28aba24c8b5e85/html5/thumbnails/43.jpg)
DITA + Agile Case Study #1
• Semiconductor industry example: Prior to move to DITA, used traditional
Waterfall method A “doc build” with their DTP program could
take as long as a day; longer if it crashed DITA opened up possibility of moving tech
docs to a more Agile approach• Results:
Considerable time saved by no longer dealing with formatting issues
Topic-based review process has greater uptake with SMEs than “here’s a whole finished manual for you to read”
Can now do daily “publication builds” of their content; early access given to tier 1 clients
![Page 44: DITA and Agile Are Made For Each Other](https://reader035.vdocuments.mx/reader035/viewer/2022062823/586fc6e31a28aba24c8b5e85/html5/thumbnails/44.jpg)
DITA + Agile Case Study #2
• Software sector example: Writers were already embedded in
software development teams, but existing DTP tools meant they were always trying to catch up
Lack of granularity meant that DTP-produced documents were hard to track
• Results: DITA + CMS means that writers now
have the time to both create content and to participate fully in the Agile process
Per topic progress reports now possible; now a regular part of scrum meetings, and can even be done on-the-fly on request
![Page 45: DITA and Agile Are Made For Each Other](https://reader035.vdocuments.mx/reader035/viewer/2022062823/586fc6e31a28aba24c8b5e85/html5/thumbnails/45.jpg)
A Tale About Commitment in Agile
Pigs produce product and are fully committed; chickens are involved and engaged but not necessarily committed. Content creators oftenstart as chickens, but become pigs as developingcontent becomes part of the product. Which are you?
![Page 46: DITA and Agile Are Made For Each Other](https://reader035.vdocuments.mx/reader035/viewer/2022062823/586fc6e31a28aba24c8b5e85/html5/thumbnails/46.jpg)
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
![Page 47: DITA and Agile Are Made For Each Other](https://reader035.vdocuments.mx/reader035/viewer/2022062823/586fc6e31a28aba24c8b5e85/html5/thumbnails/47.jpg)
Q/A
• Blog on www.ixiasoft.com• Twitter: @IXIASOFT and @KeithIXIASOFT• IXIASOFT DITA CMS Users LinkedIn group• OASIS DITA Adoption Committee articles• Member of OASIS DITA Technical Committee
Time for Q/A!