9

I think my company could benefit from adding a technical writer to the team; making sure our output is unified and of a high quality. For our current project we need to produce a range of documents, both internal and external with a range of technical depth.

Where should these people be positioned in a Scrum team? In our current project we have pushed documenting it (other than deep technical detail) out to the end of our sprints. Is this a sensible plan?

Improve this question
2
  • You don't have to have a dedicated technical writer if the rest of your team can cover that role. However, if you include one (or more), see my detailed answer below about how they should fit in. – Todd A. Jacobs♦ Nov 4 '13 at 18:49
  • I edited your question lightly to make the summary fit the body of your question. If I haven't quite captured your intent, please feel free to edit further. – Todd A. Jacobs♦ Nov 4 '13 at 18:52
5

TL;DR

In our current project we have pushed documenting it (other than deep technical detail) out to the end of our sprints. Is this a sensible plan?

Nope.

Technical Writing for Agile Teams

The Agile Maifesto values:

Working software over comprehensive documentation...[T]here is value in the items on the right, [but] we value the items on the left more.

So, what does that mean for technical writers on a cross-functional team? In my experience it means:

  1. Adequate documentation (whatever that means for the team/project) should be part of the Definition of Done.
  2. Code should be as self-documenting as possible.
  3. Test suites should function as technical documentation to the greatest extent possible.
  4. Technical writers need to be involved in Sprint Planning to identify stories and tasks where additional documentation may be needed.
  5. Technical writers need to be involved throughout the sprint to coordinate with developers and testers to make sure that the team is communicating and coordinating about documentation requirements and deliverables that must be baked into the iteration.
  6. Anything that needs documentation should be designed and developed with documentation in mind, rather than treating documentation as a last-minute bolt-on.

Technical Writers are Full-Fledged Members of the Team

No member of the team should be a second-class citizen. It reduces team cohesion and efficiency to treat technical writers as anything other than integral members of a cross-functional team.

In addition to the social dynamics and the requirements of the framework, treating technical writers as first-class citizens ensures that:

  1. Documentation tasks will be baked into your process.
  2. Knowledge transfer between coders, testers, and writers will be a constant high-bandwidth stream, rather than a last-minute set of interviews where lack of domain knowledge will tarnish the deliverables.

  3. Individuals have the chance to become cross-functional, not just the team.

    • Developers should learn something about testing and writing.
    • Testers should learn something about development and writing.
    • Technical writers should learn enough about the technical disciplines to be able to ask meaningful questions when "self-documenting" code or tests just aren't.

If you find that you need technical writers to ensure the success of your project, then they belong on the team as valued and essential contributors and should be interleaved throughout your iterative processes. Once you've made the decision to include technical writers on the team, then their inclusion within the core group is one area where your mileage should not vary.

Improve this answer
8
  • This seems to address the same point as the Agile Manifesto does - documentation for other developers on the requirements, design, implementation, and testing. In my experiences, Technical Writers write user-facing documentation (user manuals, installation instructions, deployment instructions). Some of these points may be relevant (like defining documentation in the definition of done, involvement of writers in sprint planning, baking documentation into the process), but others seem to not be. My interpretation of the question is that the focus is on writers of user-facing documents. – Thomas Owens Nov 4 '13 at 18:58
  • @ThomasOwens You're misunderstanding the Definition of Done in this context. If adding feature foo, then the Definition of Done should require a user-facing chapter in the manual about how to use this awesome new foo feature. Tossing this "over the the wall" to the tech writer at the end of the sprint is rarely the best way to provide adequate time or technical information to write effective documentation. Segregating documentation the project team cares about from documentation end-users may need creates needless project risk. YMMV. – Todd A. Jacobs♦ Nov 4 '13 at 19:38
  • I agree with that, but technical writers (unless they also have a background in developing software) won't be able to use code (regardless of how self-documenting it is) or unit tests as part of their documentation process. In addition, depending on their familiarity with the system, they may not know the extent to which a user story will lead to changes or new parts of documents (and even the team may not, until after it's designed). – Thomas Owens Nov 4 '13 at 19:48
  • 2
    @ThomasOwens you say, "integration of non-technical/non-user/non-customer entities has always been problematic", but I don't understand what you mean. I've integrated them the same way I've integrate anyone else. I've experience with various different disciplines artists, designers, business analysts, translators. Each user story should generate tasks that they're best suited to complete. The do those tasks just in time for the developer to use them. They many have specialist skills, but isn't that the same as some developers? Some developers are better suited for different programming tasks. – Dave Hillier Nov 5 '13 at 13:28
  • 1
    @CodeGnome thanks for your efforts. My concern about involving tech writers in the sprint is the potential wasted effort that might result. In our case we are creating complex business process flows for an ERP solution. The guys who will go on site and deploy these systems will have to manage the configuration, which is very complex, and is a challenge to document at all. While the code/tests are 'self documenting' to some extent, the ability to dramatically change the process flow in code is easy; yet doing this could invalidate a huge amount of work already produced by the tech writer. – PhilG Nov 6 '13 at 9:55

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.