blend well for best results - optimizing engineer and tech writer collaboration

Blend Well for Best Results:Optimizing Engineering and

Tech Writing CollaborationJody Zolli

Jody.Zolli@gmail.com

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

Questions?

Jody.zolli@gmail.com