Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

Blend Well for Best Results - Optimizing Engineer and Tech Writer Collaboration


Published on

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.

Published in: Engineering
  • Login to see the comments

  • Be the first to like this

Blend Well for Best Results - Optimizing Engineer and Tech Writer Collaboration

  1. 1. Blend Well for Best Results: Optimizing Engineering and Tech Writing Collaboration Jody Zolli
  2. 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. 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. 4. What audiences do we serve? Marketing Users Customers Management Engineers Service / Customer Support
  5. 5. We’re the Stuff that holds things together
  6. 6. But sometimes our work has been harder than it needs to be…
  7. 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. 8. Engineers would roll their eyes when they saw me coming… But I understood why….
  9. 9. In the “Over the Wall” Scenario… Technical writers were very dependent on engineers, and engineers needed little, if anything, from tech writers…
  10. 10. This created an unequal dependence between engineering and documentation…
  11. 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. 12. The key to offering more….
  13. 13. How can we build that foundation? By embedding technical writers on engineering teams, starting early in the development process.
  14. 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. 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. 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. 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. 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. 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. 20. Embedded writers can make engineering work easier in a number of ways….
  21. 21. …Helping developers organize information
  22. 22. …Creating design document templates •Requirements •Functional Specifications •User Stories •Design Specifications •User Interface Specifications
  23. 23. …Serving as an SME Embedded writers can serve as SMEs for themselves and others.
  24. 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. 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. 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. 27. But Agile can be aTwo-Edged Sword Agile methodologies are sometimes a little too flexible Fortunately they’re iterative as well…
  28. 28. Another Agile Challenge… Meetings take time
  29. 29. Beware and Agile Manifesto “Agile values working software over comprehensive documentation”
  30. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 45. So how do you get started?
  46. 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. 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. 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. 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. 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. 51. Questions?