As a tech writer, I’ve encountered a number of different processes that teams and companies have used to add documentation to their product development processes. Some of these are intentional and others are incidental—but all are used to create documentation across the software development industry.

At its most basic, the product development life cycle involves the following steps:

When you add documentation, that might look something like this:

The typical models I’ve encountered working as a tech writer can be categorized as follows:

The “throw it over the wall” model #

The “throw it over the wall” model happens when engineering and documentation teams don’t have much interaction. Instead, in a waterfall-like approach, the development team creates something and tells the documentation writer about it after it’s built.

This can happen intentionally or incidentally. Maybe an entire feature gets developed, is ready to launch, and someone lets the documentation writer know—before or after the release.

Advantages #

The advantages to this model are largely to the organization:

• Can work well across time zones where the engineering team is in one location and the writer is in another, because you don’t have to try to do synchronous work like attend the same meetings.
• Faster to write documentation because the product or feature is fully functional when the writer starts drafting. Encountering bugs during the drafting process can create a feedback loop where the writer can help improve the product and maintain (or build) empathy for the reader, but it definitely slows down drafting when key functionality is broken or not developed yet.

Disadvantages #

The disadvantages of this model are both to the customer experience:

• Little to no ability to improve or change the product in response to documentation feedback, because development is already complete. At best, the writer can file bugs or stories to get picked up later if they are validated by customer feedback. // for the product
• Inconsistent feature coverage in the documentation because only the items that get thrown over the wall as part of a request for documentation get documented. This can lead to content drift, where the docs no longer match the product in some cases, or are missing some features that could use documentation.
• Delays between feature launch and published documentation. Depending on when the feature is thrown over the wall, you can get delays between launching the feature and publishing documentation. If that happens, customers might not find out about the new feature, or if they do, don’t have any documentation to help them if they’re confused or something is broken, forcing them to file a support case if they can. Ultimately, this delay can make customers dissatisfied with your product.

And to the organization and its writers:

• Unpredictable workload for the writer. By not being involved in the planning process and finding out about a project when it lands on the other side of the wall, there’s a constant juggling of priorities with little flexibility on timelines. If every project appears as a surprise, it’s pretty difficult to plan resources or estimates.
• Pressure to write documentation quickly because documentation was left as the last step in the process, they’re seen as a bottleneck to the release process.
• Low context about the product and low rapport with the team. You might produce documentation that misses key functionality that wasn’t apparent to you when you encountered the functionality, or not have a full understanding of what was built or why, depending on what the handoff process looks like.

The “put out the latest fire” model #

This is a fairly common model, especially for overburdened documentation writers or those working as contractors or consultants on a project. You could be an external freelancer brought in to work on a specific project or be part of a documentation or content team that works with others on a project-by-project basis.

In this model, you join a project and work with that project team in an embedded or throw-it-over-the-wall fashion until the doc needs are met. You might only have one point of contact, like a product manager, and you deliver the documentation requested by them. After the project concludes, you join a different project.

Advantages #

The advantages to this model are largely to the organization:

• Lets fewer tech writers work across more projects. Whether it’s successful is debatable, due to the volume of context switching required by the writers.
• Faster onboarding onto new projects or teams, since the onus is on the project team to build the context for the writer, often to the degree of writing drafts or sending screenshots to the writer.
• Can permit flexibility in commitments, where projects without allocations go intentionally undocumented (or get delayed) because the documentation team doesn’t have the resources to support a requested project, or you can move a writer from one area to another

Disadvantages #

The disadvantages are borne by both customers and the organization:

• Results in feature-driven documentation rather than user-centric documentation. Because the writer has less context on the what, why, and for whom of the project, you can end up with feature-driven documentation that describes what was built rather than what the reader can accomplish with the new functionality.
• Estimating documentation workload is challenging due to the overlapping and intersecting projects, combined with the difficult-to-anticipate effects of context switching. More time can be spent juggling priorities than writing, and writers can quickly end up overburdened compared with their colleagues.
• Needs org-wide process consistency to be successful. If project teams don’t work using the same (or at least clearly documented) processes and rituals, the onboarding process onto a new project or team can be jarring and slow, somewhat erasing the benefits of moving writers to other projects as they’re needed.
• Docs are unowned and maintenance gets left behind. Because you leave a project as soon as you ship the documentation, there isn’t much of a concept of long-term ownership, just whoever worked on something last. Without ownership, maintenance of the documentation content is ignored in favor of the latest new feature work.

The “I’m with the team” model #

In this model, the documentation writer is treated as a full-fledged member of the engineering team, involved in all the same meetings, Slack channels, and most discussions.

Advantages #

The advantages of this approach are mostly for the customer:

• User-centric documentation rather than feature-driven documentation. If you know what is being built, why, and who for, it’s a lot easier to craft documentation that is guided by the user goals guiding product development rather than writing down what was built and how it works.
• Increased consistency in product text (and improved product quality). Because the writer is involved throughout the development and design processes, they can contribute to text in the product—whether UI text (content design) or API specifications and descriptions.
• Accelerated content development. With ultimate context and involvement on what is going on, and little if any context switching, the writer can produce documentation fairly quickly and without too much delay before and after development and testing ends.

Disadvantages #

The disadvantages of this approach are borne largely by the organization:

• It can be resource intensive. It’s often not economical to have a 1:1 writer to team ratio because not every project that engineering works on requires documentation. Of course, if engineers are working on technical debt, writers can also spend time on documentation debt or professional development, but this sort of luxurious level of staffing isn’t one that I’ve ever seen. Depending on the pace of development, the optimal writer ratio might be closer to 1:3 writer to teams, but that’s still higher than the other models.
• Writers can waste effort and get confused if they start drafting before the product is finished “enough” to start drafting. If you document every iteration of a feature flow before it is finalized, you might write the same procedure multiple times. Sometimes these drafts let you get to the most efficient and concise way of explaining something, but there’s also a risk that a writer gets attached to an incorrect mental model and the procedure ends up less clear than it might have otherwise.
• Can introduce single points of failure. If every writer is embedded in a specific team, there is a risk that if that writer goes on vacation or quits, no one else will have enough context to cover for them effectively.
• The writers can be siloed and lack visibility into other projects at the company. Because the writers spend more time with their engineering team(s) than the documentation team, this approach takes extra effort to build documentation team cohesion and consistency across the writing styles on the team.

Which model is the best? #

It depends on your priorities and circumstances!

In an ideal world, I think that the “I’m with the team” model is the one most likely to produce the best documentation — but it’s also the most resource-intensive, and therefore might not be the most feasible option for every organization.

The “put out the latest fire” model can work well at a company with low-complexity projects and consistent organization-wide procedures, making it possible to plug-and-play writers on demand to different projects. Unfortunately, many projects that require documentation also benefit from strong domain expertise and local project context, so this approach is best suited for short term transition phases at a company. After you know what projects are going to stick around and need writing commitment, you can invest in a more proactive and embedded approach like the “I’m with the team” model.

For small companies like a seed-stage startup, or one that is great at asynchronous communication, the “throw it over the wall” approach lets you add documentation without changing your core engineering processes. If you’re at the early stage where you’re prioritizing moving as fast as possible most of the time, this approach probably makes sense.