1.
Blend Well for Best Results:
Optimizing Engineering and
Tech Writing Collaboration
Jody Zolli
Jody.Zolli@gmail.com

2.
What have I been doing all this time?
• TechnicalWriter (30 years)
• Usability Evangelist (25 years)
• AgileTeam Member (10 years)
• Project Leader
• Editor/Proofreader
• Engineer Wannabe
• Writer of DoggerelVerse

3.
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
usable way

4.
What audiences do we serve?
Marketing
Users
Customers
Management
Engineers
Service / Customer Support

5.
We’re the Stuff that holds things together

6.
But sometimes our work has been
harder than it needs to be…

7.
At Some Companies…
When a project was completely
designed and built, then, and
only then, would it be thrown
over the wall to the technical
writers to document.

8.
Engineers would roll their eyes
when they saw me coming…
But I understood why….

9.
In the “Over the Wall” Scenario…
Technical writers were very dependent on
engineers, and engineers needed little, if
anything, from tech writers…

10.
This created an unequal dependence between
engineering and documentation…

11.
But writers actually have a lot to offer their
engineering teams…
If writers can build a rich understanding
of a product’s design and operation, we
can offer so much more!

12.
The key to offering more….

13.
How can we build that foundation?
By embedding technical writers on
engineering teams, starting early in the
development process.

14.
What makes embedded writers so useful?
Embedding a writer early
on is like having a CNN
reporter on a Humvee
near the front lines…..

15.
Deeper knowledge improves more than
documentation
When tech writers understand more of what
engineers typically understand, they can
contribute back to the engineering process.

16.
When we’re privy to team discussions
We gain new insight into:
• Developer priorities, perspectives, and paradigms
• Design constraints, trade-offs, and decisions

17.
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…

18.
Embedded writers can contribute to design
documents by…
• Finding inconsistencies and gaps
• Suggesting clarifications
• Pointing out assumptions
• Asking questions from the user’s
perspective

19.
We can contribute to product design by…
•Contributing to user interface text.
•Clarifying terminology.
•Helping to define and clarify user tasks and user stories.
•Identifying potential usability issues

20.
Embedded writers can make engineering work easier
in a number of ways….

21.
…Helping developers organize information

22.
…Creating design document templates
•Requirements
•Functional Specifications
•User Stories
•Design Specifications
•User Interface Specifications

23.
…Serving as an SME
Embedded writers can serve as
SMEs for themselves and others.

24.
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.

25.
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

26.
There are regular opportunities to inform developers of
what we’re working on and what support we’ll need from
team members.
•Daily check-in during stand-up meetings
•Schedule tasks and resources during sprint planning
meetings.
•Ability to create and enhance stories and tasks
Why Agile Works forTech Writers

27.
But Agile can be aTwo-Edged Sword
Agile methodologies are sometimes a little too flexible
Fortunately they’re iterative as well…

28.
Another Agile Challenge…
Meetings take time

29.
Beware and Agile Manifesto
“Agile values working software over
comprehensive documentation”

30.
Well written JIRA tasks make everyone’s job
easier…
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?

31.
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

32.
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
•Development progress
•Your current workload
•Your knowledge of the feature

33.
Scheduling Documentation Work…
•Read user stories or design documents for preliminary
information
•Use development sprints to draft more detailed
information
•Documentation may lag by a sprint
•Use hardening sprints to edit information

34.
Surfacing Documentation Issues
• The good news about agile is you’re regularly expected to share bad
news.
• 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.

35.
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
working embedded.
•Address their concerns and enlist their support.

36.
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
embedded.
•Respond to any questions or concerns the team might
have.

37.
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.

38.
I don’t have the time to review long
manuals…
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.

39.
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.

40.
Design documentation isn’t what Agile is
about….
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.

41.
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)

42.
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.

43.
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.

44.
A note to technical writers about working
embedded….
How will you find the time to read team emails as
well as wiki content, JIRA issues, and design
documents?
You’ll soon learn how to scan incoming information
and glean the most relevant parts, and identify the
level of detail you need..

45.
So how do you get started?

46.
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
information
• Get access to locations with other relevant content including
roadmaps, project plans, troubleshooting and support
information, and even test cases.

47.
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.

48.
StepThree: Get Invited to Meetings
• Find out when and where routine meetings are held.
• Listen for upcoming design discussions.
• Ask to be invited.

49.
Summary: What Developers Need to Do
Add writers to team mailing lists.
Include writers in Agile, planning, or
design discussions and review
meetings.
Point writers to roadmaps,
requirements, goals, use cases, wiki
areas, design documents, and
project plans.
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
information.
Provide access to support or
troubleshooting information.
Put writers in touch with service
and support who can help them
understand customer pain points
so they can be addressed in
documentation deliverables.

50.
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

51.
Questions?
Jody.zolli@gmail.com