blend well for best results - optimizing engineer and tech writer collaboration
TRANSCRIPT
Blend Well for Best Results:Optimizing Engineering and
Tech Writing CollaborationJody Zolli
What have I been doing all this time?
• Technical Writer (30 years)• Usability Evangelist (25 years)• Agile Team Member (10 years)• Project Leader• Editor/Proofreader• Engineer Wannabe• Writer of Doggerel Verse
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
What audiences do we serve?
Marketing
Users
Customers
Management
Engineers
Service / Customer Support
We’re the Stuff that holds things together
But sometimes our work has beenharder than it needs to be…
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.
Engineers would roll their eyeswhen they saw me coming…
But I understood why….
In the “Over the Wall” Scenario…
Technical writers were very dependent on engineers, and engineers needed little, if anything, from tech writers…
This created an unequal dependence betweenengineering and documentation…
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!
The key to offering more….
…wholly depends on when and how well the writer understands the subject matter.
How can we build that foundation?
By embedding technical writers on engineering teams, starting early in the development process.
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 documentation
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 documents by…• Finding inconsistencies and
gaps• Suggesting clarifications• Pointing out assumptions• Asking questions from the
user’s perspective
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
Embedded writers can make engineering work easier in a number of ways….
…Helping developers organize information
…Creating design document templates
•Requirements•Functional Specifications•User Stories•Design Specifications•User Interface Specifications
…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 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 for Tech Writers
But Agile can be a Two-Edged Sword
Agile methodologies are sometimes a little too flexibleFortunately they’re iterative as well…
Another Agile Challenge…
Meetings take time
Beware and Agile Manifesto
“Agile values working software over comprehensive
documentation”
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?Recommended Test 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 Opportune TimeWith 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
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
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.
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.
Getting Buy-in from your Engineering Team•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.
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 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.
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 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.
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 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..
So how do you get started?
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.
Step Two: 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.
Step Three: 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 DoAdd 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.
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
