Search results

Tech docs and Agile: Alternatives to integrating into engineering Scrums (Part 2)

by Tom Johnson on Aug 4, 2017
categories: technical-writing podcasts

This is part two in a series on Agile and tech docs. In the previous post, I outlined challenges in integrating into engineering Scrum teams. Some alternatives to Scrum include Kanban, Extreme programming, Waterfall, and various productivity methodologies. The most compelling solution, to me, seems to be to form your own documentation-focused Scrum. This allows you to keep with the same project management approach and language in the company, while also allowing you to avoid the pitfalls previously described with integrating into an engineering Scrum. Even so, there's not an extremely compelling reason for docs to adopt Scrum, so its main aid might be to give you a disciplined approach to your doc work.

Listen here:

A new model?

Before I jump into alternatives and solutions, first remember that some byproducts of Scrum will always be part of your tech doc experience (assuming your developers follow Scrum). These byproducts include the following:

  • Uncertainty about long-term planning
  • The possibility of multiple doc revisions from course corrections
  • Lack of requirements documentation or other details to orient you
  • Regular releases (possibly biweekly) that you have to keep pace with

Even if you reject Scrum as a methodology for yourself, you’ll still be writing docs in an Agile workplace. The questions I’ve been exploring are these: As a technical writer, do you also try to integrate into the Scrum team to manage your work? Do you renounce it altogether and say bah humbug to the litany of Scrum meetings? Do you replace scrum with another methodology? What other methodology options are there?

Kanban

As one alternative, you could incorporate a Kanban approach. In a nutshell, Kanban limits the flow of work to a manageable rate.

To implement Kanban, you first model your flow of work. For example, doc items might move through 5 stages:

  1. Research
  2. Demo
  3. Draft
  4. Review
  5. Publish

You then decide the limits of the items for each column. You might allow 10 items in Research, 3 items in Demo, 2 items in Draft, 5 items in Review, and 3 items in Publish. An item can’t move from one stage to the next until you clear some space for it. Hence you might need to unblock the flow of items.

The idea is that through your Kanban workflow, you unblock tasks that get stuck and keep the items moving through your workflow.

Waterfall

Another approach would be the Waterfall approach. You create a doc plan, you draft an outline of all the topics you plan to write, estimate the time it will take you to finish all the topics, and then present this plan to the team.

For example, suppose you estimate that there are about 20 topics the user guide should cover, and each topic will take approximately 4 hours to write. Overall, the project will take about 80 hours, or two weeks of heads-down, 8-hour days.

Since no one works more than 6 hours a day on actual projects (the rest of the time gets consumed by meetings, coffee breaks, conversations with colleagues, and figurative ping pong), and you’re also working on three other projects, you can estimate 2 hours a day, or 8 weeks, to finish the project.

But you can already see the reason why waterfall was abandoned. Will there really be exactly 20 topics? Will you really work 2 hours a day on them consistently? Will they really take just 4 hours per topic? The 8-week estimation may look good on paper, but I’m betting that the reality will play out differently. The estimations will be as accurate as a long-term weather forecast.

Further, because Scrum teams plan their work out only two weeks in advance, you can’t always plan longer than that. You can’t know for certain the longevity of the Scrum team’s work, the amount of doc (because it depends on the features coded), or the long-term direction. Unless you’re really far behind with the documentation, your doc plan is only as good as their planned sprint.

Extreme Programming

Another approach is Extreme Programming. As an Agile philosophy, Extreme Programming approach also involves “frequent ‘releases’ in short development cycles, which is intended to improve productivity and introduce checkpoints at which new customer requirements can be adopted.”

With Extreme Programming and docs, you might start with bare-bones documentation and add to it in a quick, dynamic way as it’s needed. You maintain close contact with customers and their frequently changing information needs and feedback. You might follow pair programming, in which two writers work together on the same content. By working in pairs, you have someone immediately QAing your work, catching errors in real time and helping you be more efficient.

Tim Ferriss’ 4-hour Work Week

There are also a variety of personal productivity (getting-things-done) type approaches to work. I wrote about one of them in a post called Applying Tim Ferriss’ 4-hour work week rules to tech comm projects.

In a nutshell, everyday you wake up, look at the two highest-priority tasks you want to tackle for that day, and focus on them first. You block out all other distractions (email, meetings, phone calls, etc.) until you’ve finished these two tasks. (In this model, the many Scrum meetings you usually attend might be a huge deterrent to productivity.)

No methodology at all

Finally, there’s using no methodology at all, which I suspect is the most common. With this approach, you sort of bounce from task to task as people ask for things. The louder someone screams for a doc, the more attention you put on it. And if no one is screaming for doc, you gravitate toward the doc you actually want to work on. (And you probably spend a lot of time on Slack.)

What about Lean?

I need to add a note about Lean, because it’s related here. Lean isn’t a methodology like Scrum. Lean might use Kanban or Kaizen (continuous improvement) as a methodology. Instead, Lean is more of a high-level philosophy, similar to Agile, about reducing waste and increasing value to the user.

Whereas Agile “is aimed at executing tasks faster, adapting to changes easier,” Lean aims to “improve virtually everything you do by eliminating anything that doesn’t bring value to the customer” (How to choose between Agile and Lean, Scrum and Kanban — which methodology is the best?). Agile philosophy is actually a subset of Lean philosophy.

Mark Baker has a lot of insight about applying Lean principles to docs. See Mark’s four-part series:

Mark examines ways to eliminate the frequency of errors in tech docs. Sure, revision is helpful. But why are there errors in the first place, he asks, and how can we avoid them? And how can we increase the value of our doc efforts? That which doesn’t produce value can be considered waste.

Mark says, “Don’t just try to fit into development’s Agile process. Create your own lean content development process” (Don’t Lean on Development’s Agile Process). He warns that Agile Scrum integrations often lead tech writers to create product-centered documentation rather than user-centered documentation (I touched on this point in my previous post).

Lean’s philosophy of reducing waste and increasing value in docs should be strategies for any tech writer. The question is what methodology (Scrum, Kanban, Kaizen, Waterfall, Tim Feiress’ approach) one should use to implement Lean and Agile principles. I’ll probably circle back to Lean in another post.

Doc teams with their own Scrum

Another alternative might be to create your own Scrum that consists entirely of documentation tasks from all your various projects. I’m not the only one to propose this shift towards documentation Scrums. For example, in a Linkedin thread, Petko Mihailov says:

Seems like it would be useful to either exempt the documentation from the Agile process and … consider the documentation a product per se and have an Agile documentation team with its own sprints, whose members work in tight collaboration with the Agile development teams… (Product vs. User Perspective in Agile Documentation)

Mark Baker also seems to recommend a similar approach:

This is why I always advise tech comm groups not to simply integrate writers into development’s Agile process, but to develop their own lean/Agile process and optimize the interface between their process and development’s process. (Don’t Lean on Development’s Agile Process)

In a forum thread on a Scrum site, one Scrum master explains the difficulty of integrating a tech writer. After some back and forth (for example, separate user stories for docs, or separate sprints), he concludes:

… One tech writer can’t be divided in 4-5 Sprints. I think I would go with separate project for documentation until I sort out the resource constraint issue and let the regular Sprints move ahead. (Technical writer in Scrum team)

Here’s another thread on the same Scrum.org site where a documentation team formed its own Scrum. This is my favorite thread. Gina asks Joshua about how to integrate a tech writer who is allocated to multiple projects into the various Scrum teams.

Gina writes:

… Until recently, the writers were part of the teams, but the documentation team grew along with the company and we became our own Scrum team…. So my questions are: Do others work this way? And, if so, how exactly do you integrate documentation into the release cycles of all the teams? Gina

Hi Gina,

Is there any specific reason why the documentation team needs to be its own team instead of having each documentation team members embedded with the engineers?

Joshua

Hi Joshua,

We used to work with writers embedded in the teams, but the set up was such that one writer had to cater to three, four, sometimes five teams. It became unworkable. Plus during holidays or when someone fell ill, there were huge issues to solve. Of course, capacity is still something we struggle with, but at least now we can divide the work better and become each other’s safety net.

Gina

Hi Gina,

Why does it become unworkable? Did you discuss it with the engineers during retrospectives?

Joshua …

Hi Joshua,

We did. But being part of three to five teams and thus three to five retros, groomings (usually this one was twice a week), plannings and daily stand ups, was taking away too much time. Not attending these meetings, or just a few, resulted in not entirely being part of the teams. Plus, it is difficult to fully be a part of three teams anyway. We couldn’t commit.

Now, with our own team, we can attend our own meetings and talk to the SMEs in our own time, outside of meetings. That bit works very well. Now the integration of the rest of our process…

Gina

(See Technical documentation/translation in Scrum)

There’s good logic for following Scrum methodology. Even with its flaws, it’s how software companies do work. If you try to shoehorn another approach, others (at least in Engineering) won’t understand how to work with you.

For example, when engineers need a feature documented, their first inclination is to log an issue for it and assign it to you. It’s simply how tasks are managed. If you want someone to review the doc, you assign them a similar task.

The next logical question, after they log the task, is to wonder when the task will be completed. The idea that the task will be assigned into a sprint, and then completed during that sprint, is a natural flow for others working in Scrum. (Even if you aren’t using Scrum, they’ll expect the task to integrate into some kind of workflow.)

When you follow Scrum to do work in IT, people automatically understand how to work with you. But rather than trying to integrate into engineering Scrums, tech writers can create and manage their own Scrum projects focused entirely on documentation tasks. These tasks would mostly be consolidated from other scrum teams.

How a user documentation Scrum might work

How exactly would it work to create Scrum for a single technical writer or a group of tech writers (all working on different projects)? Here are the basics.

Scope. The user documentation Scrum includes documentation tasks from all projects you’re working on. (Hopefully all your teams use the same system, but if not, you could create pointers to tasks that live in other systems.)

Sprint planning. During sprint planning, you identify the highest priority tasks (pulling from the backlog) to work on during the two-week sprint. You estimate points (or general sizes) for those tasks, being careful not to over-extend what you can feasibly accomplish during the two-week sprint.

Regular reviews. As you complete each doc task, you submit it to the appropriate people (engineers, project managers, marketers, users) for review. By the end of the two weeks, all tasks should have been submitted out for review. There’s no need for a single demo session at the end.

Protecting the scope of sprint work. At any time, people can look at your work and see what you’re working on. If you get inundated with requests, you have a sprint plan you can direct people to. You can say, here are the documentation tasks I’m working on during this sprint (which spans this timeframe). Their task (if high enough priority) can be initiated during the next sprint. This visibility into your task load can help others understand the process and status for their requests.

Daily standup. Some Scrum mechanics, such as the daily standup, might seem kind of odd when undertaken by a team of one. But the principle is the important point, not the mechanics. You don’t have to literally stand up and give a two-minute report to yourself about what you did yesterday, what you’re doing today, and what blockers are getting in your way. But surely it’s good to spend at least two minutes planning your day’s activities each morning, and to escalate any blockers following the appropriate resolution path.

During this figurative standup time, you can also reach out to the people who requested the doc and let them know the status of the task. They should be watching the task in the project anyway, so adding comments on the task items could be sufficient.

Retrospectives. Retrospectives are also helpful — reflecting on what went well and what could be improved helps contribute to continuous improvement. We don’t just slog task after task without ever stopping to look outside the breakroom window and think about the work we’re doing. Why not formalize this a bit more, if only during documentation meetings or with your manager during one-on-one’s?

Overall, the Scrum structure can infuse your daily work with a discipline that is helpful. If nothing more, it can assist in planning and execution of your tasks. It’s an approach to getting things done. There are many getting-things-done approaches, but this is the approach that software companies follow.

Biweekly user check-in. Perhaps the most important aspect of Scrum is gathering user feedback after short cycles of work. How would you achieve this with docs that haven’t been released? You hope that the reviewers represent the users (for this reason, it would be good to include reviewers across marketing, support, product management, and engineering to get a variety of perspectives). It would also be good practice to gather feedback from real users from already published documentation, even if it doesn’t directly address the doc work you did during the sprint. The feedback can inform your overall doc direction, which probably is pretty similar to your current work.

No irrelevant meetings

Running your own Scrum project, you’re guaranteed not to be sucked into any irrelevant, time-wasting meetings. You become an active, self-directed technical writer who is managing and moving forward the documentation work for your products. And you’re following principles that should make you more efficient and productive.

You drive the backlog

When you’re the one driving the project, you have control about the user stories and other tasks you tackle. Rather than taking orders from a project manager about the needed docs, you can survey the industry, technology, and business domains as an active product researcher to determine what documentation gaps need to be addressed. (I wrote about the need to be an active researcher here: How do you learn what you need to learn to be successful as a technical writer?)

Of course, in many cases, much of your work might stem from project managers and their scrums. But the user stories should also originate from your active, self-directed research looking at forums, support tickets, industry blogs, and other feedback.

Finding a unified focus

Because the documentation project is a consolidation of tasks across different projects, your work might not be unified toward building a specific project. But within a larger perspective, you’re adding to documentation that has a common goal. In my case, I help 3rd party developers build Fire TV apps for the Amazon Appstore. All of my doc work usually rolls up under this larger umbrella.

Pros and cons for creating your own documentation-focused Scrum

Now that I’ve outlined what your user documentation Scrum might look like, let’s look at some pros and cons for this model.

Pros

Scrum is the workflow language that engineers live and breathe, and your interactions with engineers and project managers will be better if you follow a similar methodology. You will speak the same language and follow similar principles.

Additionally, by being a diligent follower of Scrum yourself, you’ll increase your understanding of its principles and mechanics and by so doing, increase your understanding of other Scrum team dynamics.

For example, when I first learned the philosophy and principles of Scrum, it helped me understand how software teams get work done, and that helped me interact better with engineering teams. I realized that nothing gets done without a JIRA item, and that item has to be assigned to a sprint. I learned to be patient and hold back on trying to change the scope of a planned sprint. The time to petition for change is during sprint planning.

When I finally understood Scrum, I learned how to check the pulse of any project. You locate the team’s current sprint to see what tasks the team is working on (and who is working on them). By understanding dates for demos, you can gather information you need. You can also find the right engineer to talk with by looking at who is tackling the JIRA items.

Scrum is as standard as distributed version control (such as git) but with project management. You could use another system other than distributed version control (such Dropbox), but everyone else in engineering will be using distributed version control, so you better learn it if you want to interact with engineers.

Cons

While it seems like there are a lot of pros, the cons also stack up. For starters, separating your work into your own user documentation Scrum lessens the communication with the team. They won’t see you or understand your role as much. Further, if documentation is entirely decoupled from the sprint, they may disregard (or forget) the work of documentation even more.

Additionally, Agile’s core philosophy of satisfying customers through regular check-ins to make sure your design is on track might be somewhat irrelevant. These biweekly checkins don’t matter as much to the work of documentation. We already know what users want and need: clear, easy-to-follow, helpful instructions. It’s not a feature guessing game like it is with product development and design.

When a team develops a product, they make a lot of design decisions about what features to include, what UI and workflow to follow, how to integrate into the user’s business environment, etc. These decisions need to be evaluated by the users, and that feedback helps inform the design decisions.

Ultimately, documentation just describes the features the design team implements, so there’s not much flexibility in deciding what features to include or not in documentation. (You document what was designed.) What’s left is feedback about the approach taken in docs (the organization, findability, terms used, style, etc. in the docs). As long as you align with documentation best practices, you’re following a good path.

Since docs won’t benefit that much from these frequent check-ins with users, adopting Agile as a philosophy and Scrum as a methodology is less important. Scrum might not be the best fit. Sure, documentation is part of the product, but so is Marketing and Support, and these groups don’t usually implement Scrum.

If you take away Agile’s core benefit, you’re left with some Scrum mechanics that may be meaningless without the need to communicate across a larger team. The standups, sprint planning, retrospectives, and demos could be replaced with commonsense planning and task management.

Conclusion

I’ve evaluated the pros and cons of creating a user documentation Scrum. What’s my verdict? I see logic for taking either route, really. But since I’m an experimenter, and I’m yearning for some method to my work, I think I’ll experiment with my own documentation Scrum. But let’s be real — I don’t think it will revolutionize my productivity or suddenly make my docs great. I’m adopting it to have a disciplined and consistent approach to getting work done in an Agile software environment.

It might work out great, or not. Most methodologies would work well enough if we only maintained the discipline of following them. I suspect that continuing the initial plan is the hardest part. In a team that has adopted Agile, you have others that help you continue the daily standups, sprint planning, demos, retrospectives, and other Scrum mechanics.

But if you’re going about it all on your own, it will be easy to discard elements that seem dumb, or to alter processes as you see fit, and if desired, try something else entirely on a whim. That fragility for the process can’t be good, so in all reality, my excitement for the process might be forgotten in a few weeks. Perhaps in an upcoming post, I’ll explore strategies for staying the course in whatever task management methodology you’ve chosen.

If you’d like to read more about tech comm and Scrum, see the following:

About Tom Johnson

Tom Johnson

I'm an API technical writer based in the Seattle area. On this blog, I write about topics related to technical writing and communication — such as software documentation, API documentation, AI, information architecture, content strategy, writing processes, plain language, tech comm careers, and more. Check out my API documentation course if you're looking for more info about documenting APIs. Or see my posts on AI and AI course section for more on the latest in AI and tech comm.

If you're a technical writer and want to keep on top of the latest trends in the tech comm, be sure to subscribe to email updates below. You can also learn more about me or contact me. Finally, note that the opinions I express on my blog are my own points of view, not that of my employer.