Agile development can introduce new challenges to the information design process, but in the context of bringing technical writers into the development team and the development work itself, agile can present unique opportunities for technical writers. Earlier and deeper involvement in development projects enables technical writers to attain a rich understanding of a product’s design, operation, and end-users, and invites them to contribute to the engineering design and development process as they develop highly usable information for the product’s target audience. Technical writers have so much more to offer than end-user documentation, and it’s been my experience that working more closely with development teams enables writers to contribute on multiple fronts while they are cultivating the in-depth product knowledge necessary for writing high quality product documentation.
Blend Well for Best Results - Optimizing Engineer and Tech Writer Collaboration
Blend Well for Best Results:
Optimizing Engineering and
Tech Writing Collaboration
What have I been doing all this time?
• TechnicalWriter (30 years)
• Usability Evangelist (25 years)
• AgileTeam Member (10 years)
• Project Leader
• Engineer Wannabe
• Writer of DoggerelVerse
How do we do our work?
Analyze the audience and their needs
Analyze the product or process and its interface
Generate, organize, and deliver information in a highly
What audiences do we serve?
Service / Customer Support
How can we build that foundation?
By embedding technical writers on
engineering teams, starting early in the
What makes embedded writers so useful?
Embedding a writer early
on is like having a CNN
reporter on a Humvee
near the front lines…..
Deeper knowledge improves more than
When tech writers understand more of what
engineers typically understand, they can
contribute back to the engineering process.
When we’re privy to team discussions
We gain new insight into:
• Developer priorities, perspectives, and paradigms
• Design constraints, trade-offs, and decisions
Transforming the Relationship
When tech writers understand how a product was
designed, and the nuances of its operation, the
relationship between writers and engineers can change.
We can give back in several ways…
Embedded writers can contribute to design
• Finding inconsistencies and gaps
• Suggesting clarifications
• Pointing out assumptions
• Asking questions from the user’s
We can contribute to product design by…
•Contributing to user interface text.
•Helping to define and clarify user tasks and user stories.
•Identifying potential usability issues
Embedded writers can make engineering work easier
in a number of ways….
…Serving as an SME
Embedded writers can serve as
SMEs for themselves and others.
Agile is a good way to get embedded…..
Use of the Agile process isn’t
the only way to get embedded
on a development team, but it
is often a natural way to do so.
Why Agile Works for Everybody
•It’s no longer “us” and “them”; it’s all “us”
•You get to know who knows what
•Problems show up very quickly; focus is on getting it done
•Continuous course correction keeps the project on track
•Making sure each story is “done” avoids surprises and
reduces technical debt
There are regular opportunities to inform developers of
what we’re working on and what support we’ll need from
•Daily check-in during stand-up meetings
•Schedule tasks and resources during sprint planning
•Ability to create and enhance stories and tasks
Why Agile Works forTech Writers
But Agile can be aTwo-Edged Sword
Agile methodologies are sometimes a little too flexible
Fortunately they’re iterative as well…
Beware and Agile Manifesto
“Agile values working software over
Well written JIRA tasks make everyone’s job
JIRA field What it can tell you
Owner Who is responsible for a given task?
Epic / Story /Task / Subtask How complex is the task, and what does it entail?
Points How long will this work take?
Release Date When will the task be completed?
User Story How will this affect the user experience?
Definition of Done How will this feature work?
RecommendedTest Case What procedures are associated with this feature?
Defining Documentation Stories…
• Helps make your work visible
• Helps engineers understand what you do and how you do it
• Enables you to assign tasks to SMEs (information gathering or review)
• You may need separate stories for more complex or derived information
such as troubleshooting, conceptual, best practice, or reference material.
• Allows you to indicate when tasks are blocked so resources can be assigned
to unblock them
Wait Until the OpportuneTime
With Agile, you need to focus more on documenting
features at the right time, which can depend on:
•A story’s completeness
•Design document maturity
•Your current workload
•Your knowledge of the feature
Scheduling Documentation Work…
•Read user stories or design documents for preliminary
•Use development sprints to draft more detailed
•Documentation may lag by a sprint
•Use hardening sprints to edit information
Surfacing Documentation Issues
• The good news about agile is you’re regularly expected to share bad
• As part of the daily stand-up meeting, team members announce
whether or not they are blocked.
• Once you share that you’re blocked, you can ask the team to suggest
methods or resources that will help you get “unblocked”.
• If you find that your work is routinely blocked, for example because
SMEs are not making themselves available during scheduled sprints,
bring this issue up at the sprint retrospective.
Getting Buy-in from your Manager
•If other tech writers already doing this, ask them for
details about how they started their embedded work.
•Talk to your manager and explain the benefits of
•Address their concerns and enlist their support.
Getting Buy-in from your EngineeringTeam
•Talk to the appropriate people on your development team
and get them enrolled.
•Let them know the process and benefits of working
•Respond to any questions or concerns the team might
What if the writer asks too many questions?
Answer: We won’t.
Good writers will gather all available information
and review it before asking questions of SMEs, so
we’re only asking the questions we need to.
I don’t have the time to review long
Answer: We know you don’t.
•Writers can highlight new or updated
information to make reviewing easier.
•In Agile, it’s often only small information sets
that are ready for review in a given sprint.
Won’t the writer take over our meetings?
Answer: Absolutely not.
•Writers participate in meetings the same way
engineers do, supporting the goal of the meeting.
•When a writer needs to focus specifically on
documentation planning or review, we’ll schedule a
separate meeting to do so, inviting only those team
members we require.
Design documentation isn’t what Agile is
Answer: But you can’t succeed without it.
The Agile manifesto indicates that Agile values “working
software over comprehensive documentation.” But that
doesn’t mean you don’t need any design documentation.
Goldilocks Design Information
At a minimum, Agile teams should document:
•What decisions the team made and why
•Priorities (and changes in priority)
•Requirements (and changes in requirements)
•Basic design information (enough detail to scope and
plan the work)
Why does the writer need a demo?
Can’t they just read the spec?
Answer: We will read the spec, but giving even a brief
demo will save considerable discussion and time.
Teach a Writer to Fish…
•Find out how to access software in development.
•Report bugs if you find them.
•Usage can also help uncover “aha” information.
A note to technical writers about working
How will you find the time to read team emails as
well as wiki content, JIRA issues, and design
You’ll soon learn how to scan incoming information
and glean the most relevant parts, and identify the
level of detail you need..
Step One: Get Access to Information
• Get added to any team mailing lists
• Get access to the tool where the team enters and tracks its
work / stories
• Get access to locations where the team stores its design
• Get access to locations with other relevant content including
roadmaps, project plans, troubleshooting and support
information, and even test cases.
StepTwo: Let the Software do the Work
Use common software tools to set up
watches/alerts/feeds on relevant JIRA issues,
and wiki and design information areas.
StepThree: Get Invited to Meetings
• Find out when and where routine meetings are held.
• Listen for upcoming design discussions.
• Ask to be invited.
Summary: What Developers Need to Do
Add writers to team mailing lists.
Include writers in Agile, planning, or
design discussions and review
Point writers to roadmaps,
requirements, goals, use cases, wiki
areas, design documents, and
Include documentation deliverables
on the engineering roadmap and in
the Agile process.
Give writers access to systems
running software under test.
Send writers to task tracking
systems to gather and contribute
Provide access to support or
Put writers in touch with service
and support who can help them
understand customer pain points
so they can be addressed in
Working with Other Embedded Writers
If there are several embedded writers at your company, share….
• How to keep up with engineering information
• How you can best participate in engineering meetings
• How best to support creation of design documentation
• How best to contribute to increased usability
• How to collaborate on and capture best practices