DITA and Agile are Made for Each Other by Keith Schengili-Roberts, IXIASOFT DITA Specialist. Presented at CMS/DITA North America 2016 in Reston, Virginia.
Agile software development makes specific demands on documentation teams, whose content creators now need to be more nimble, describe features in a piece-meal fashion, and report on their progress in an effective way. The topic-based structure of DITA is ideally suited to these needs. Keith Schengili-Roberts (also known as “DITAWriter”) focuses on how DITA-based content is the optimal way of working in an Agile environment, enabling content creators to effectively meet the demands of short sprint cycles, measure content output for Scrum meetings, and how to become a pig rather than staying a chicken (yes, seriously). Keith also looks at several case studies of DITA-using documentation groups working within an Agile environment. If you are wondering about what the impacts are of working with Agile or are simply looking to optimize your DITA-based documentation processes, come to this presentation!
What can the audience expect to learn?
Keith expands upon the material that was touched upon during the Best Practices conference on the same subject, including information based on subsequent interviews with clients and other content creators who are using DITA in an Agile environment. He provides information on how others are using DITA in this scenario and emerging best practices within it. Keith has found that many content creators using DITA are looking to move to an Agile environment—particularly if they work for a software firm. The ideas presented here serve as an introduction on what to expect. Even those who do not fit this scenario may find some of the ways and processes used by DITA-using doc groups in an Agile team to be beneficial.
Harnessing ChatGPT - Elevating Productivity in Today's Agile Environment
DITA and Agile Are Made For Each Other
1. DITA and Agile are
Made for Each Other
Keith Schengili-Roberts
DITA Information Architect, IXIASOFT
2. 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
3. Who’s This Guy?
• Keith Schengili-Roberts
What 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
4. 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
5. 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 tech
writers and managers about their Agile + DITA experiences
6. 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”
7. 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
8. 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
9. 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”
10. 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)
11. 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-1990s
Pre-Agile, definitely Waterfall
12. 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
13. 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
14. 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
15. 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)
16. 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
18. DITA is Clearly Popular Among Agile Teams
• DITA is the most popular form of structured content used
by Agile teams (data from LinkedIn):
19. Development of Agile
• Agile Manifesto written in 2001:
• A clear difference from the traditional waterfall approach to docs
20. 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
21. 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
22. 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
24. 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.
25. Why DITA + Agile = A Great Partnership!
DITA Agile
Topic-based approach Incremental development; can update
topics as required; self-contained
Task topics User stories; content is focused
squarely on what user needs to do
Individual 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
26. 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
27. 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”
28. • 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
29. 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
30. 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
31. 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
32. 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
33. 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
34. 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
35. 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
36. 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”
37. 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
38. 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
39. 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
40. 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
41. 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
42. 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:
43. 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
44. 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
45. A Tale About Commitment in Agile
Pigs produce product and are fully committed;
chickens are involved and engaged but not
necessarily committed. Content creators often
start as chickens, but become pigs as developing
content becomes part of the product. Which are you?
46. 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
47. 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!
Hinweis der Redaktion
A pair of Darwin’s finches; the relationship between DITA and Agile is not always easy, but as you will see, they really are made for each other
Waterfall is the process I learned when I first got into Technical Documentation 25+ years ago
Information on left is from DITAWriter.com, chart on right derived from 10th Annual State of Agile Survey from VersionOne
People do not want to be perceived as not being Agile (even if they do not fully know what that is)
Last point is a hallmark of Kanban in general
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
Quote is from Tim Grantham’s slidedeck on Agile documentation: http://www.slideshare.net/abelsp/your-global-audience-is-already-here-how-to-create-content-that-communicates-with-nonenglish-speakers-at-home-and-abroad-485133
Result is from Buchanan presentation: “No longer author a lot of UI related "how to" info. We use our work with UX to ensure screens are useable and self-documenting focusing on progressive disclosure. “
Example is from Ixiasoft’s own online DITA CMS documentation
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
Quote is from an interview I did with Jason Owen from his Agile experience at TruePosition
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 understaffed. In the end that 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.
This example came from Nathalie Laroche from her experiences with two different Agile teams