Learn how to add documentation to your product life cycle
As a tech author, I’ve encountered numerous totally different processes that groups and firms have used to
add documentation to their product growth processes. A few of these are intentional and others are
incidental—however all are used to create documentation throughout the software program growth trade.
At its most simple, the product growth life cycle entails the next steps:
Whenever you add documentation, that may look one thing like this:
The everyday fashions I’ve encountered working as a tech author could be categorized as follows:
The “throw it over the wall” mannequin
The “throw it over the wall” mannequin occurs when engineering and documentation groups don’t have a lot
interplay. As a substitute, in a waterfall-like strategy, the event crew creates one thing and tells the
documentation author about it after it’s constructed.
This could occur deliberately or by the way. Possibly a complete characteristic will get developed, is able to launch, and somebody lets the documentation author know—earlier than or after the discharge.
Benefits
The benefits to this mannequin are largely to the group:
- Can work effectively throughout time zones the place the engineering crew is in a single location and the author is in
one other, since you don’t need to attempt to do synchronous work like attend the identical conferences. - Quicker to put in writing documentation as a result of the product or characteristic is absolutely practical when the author begins
drafting. Encountering bugs through the drafting course of can create a suggestions loop the place the author might help
enhance the product and keep (or construct) empathy for the reader, however it positively slows down
drafting when key performance is damaged or not developed but.
Disadvantages
The disadvantages of this mannequin are each to the shopper expertise:
- Little to no capability to enhance or change the product in response to documentation suggestions, as a result of
growth is already full. At greatest, the author can file bugs or tales to get picked up later in the event that they
are validated by buyer suggestions. // for the product - Inconsistent characteristic protection within the documentation as a result of solely the objects that get thrown over the wall
as a part of a request for documentation get documented. This could result in content material drift, the place the docs no
longer match the product in some instances, or are lacking some options that would use documentation. - Delays between characteristic launch and revealed documentation. Relying on when the characteristic is thrown over
the wall, you may get delays between launching the characteristic and publishing documentation. If that occurs,
clients may not discover out in regards to the new characteristic, or in the event that they do, don’t have any documentation to assist them
in the event that they’re confused or one thing is damaged, forcing them to file a assist case if they will.
In the end, this delay could make clients dissatisfied along with your product.
And to the group and its writers:
- Unpredictable workload for the author. By not being concerned within the planning course of and discovering out
a couple of mission when it lands on the opposite aspect of the wall, there’s a continuing juggling of priorities with
little flexibility on timelines. If each mission seems as a shock, it’s fairly tough to
plan sources or estimates. - Strain to put in writing documentation shortly as a result of documentation was left because the final step within the course of,
they’re seen as a bottleneck to the discharge course of. - Low context in regards to the product and low rapport with the crew. You may produce documentation that misses
key performance that wasn’t obvious to you if you encountered the performance, or not have a full
understanding of what was constructed or why, relying on what the handoff course of seems to be like.
The “put out the newest hearth” mannequin
This can be a pretty frequent mannequin, particularly for overburdened documentation writers or these working as
contractors or consultants on a mission. You would be an exterior freelancer introduced in to work on a selected
mission or be a part of a documentation or content material crew that works with others on a project-by-project foundation.
Benefits
The benefits to this mannequin are largely to the group:
- Lets fewer tech writers work throughout extra initiatives. Whether or not it’s profitable is debatable, as a result of
quantity of context switching required by the writers. - Quicker onboarding onto new initiatives or groups, for the reason that onus is on the mission crew to construct the context
for the author, typically to the diploma of writing drafts or sending screenshots to the author. - Can allow flexibility in commitments, the place initiatives with out allocations go deliberately undocumented
(or get delayed) as a result of the documentation crew doesn’t have the sources to assist a requested mission,
or you possibly can transfer a author from one space to a different
Disadvantages
The disadvantages are borne by each clients and the group:
- Leads to feature-driven documentation somewhat than user-centric documentation.
As a result of the author has much less context on the what, why, and for whom of the mission, you possibly can find yourself with
feature-driven documentation that describes what was constructed somewhat than what the reader can accomplish
with the brand new performance. - Estimating documentation workload is difficult as a result of overlapping and intersecting initiatives,
mixed with the difficult-to-anticipate results of context switching. Extra time could be spent juggling priorities than writing, and writers can shortly find yourself overburdened in contrast with their colleagues. - Wants org-wide course of consistency to achieve success. If mission groups don’t work utilizing the identical (or at
least clearly documented) processes and rituals, the onboarding course of onto a brand new mission or crew could be
jarring and gradual, considerably erasing the advantages of shifting writers to different initiatives as they’re wanted.
The “I’m with the crew” mannequin
On this mannequin, the documentation author is handled as a full-fledged member of the engineering crew, concerned
in all the identical conferences, Slack channels, and most discussions.
Benefits
The benefits of this strategy are principally for the shopper:
- Consumer-centric documentation somewhat than feature-driven documentation. If you realize what’s being constructed,
why, and who for, it’s quite a bit simpler to craft documentation that’s guided by the person targets guiding product
growth somewhat than writing down what was constructed and the way it works. - Elevated consistency in product textual content (and improved product high quality). As a result of the author is concerned
all through the event and design processes, they will contribute to textual content within the product—whether or not UI textual content
(content material design) or API specs and descriptions. - Accelerated content material growth. With final context and involvement on what’s going on, and little
if any context switching, the author can produce documentation pretty shortly and with out an excessive amount of delay
earlier than and after growth and testing ends.
Disadvantages
The disadvantages of this strategy are borne largely by the group:
- It may be useful resource intensive. It’s typically not economical to have a 1:1 author to crew ratio as a result of not
each mission that engineering works on requires documentation. In fact, if engineers are engaged on
technical debt, writers may also spend time on documentation debt or skilled growth, however this type
of luxurious degree of staffing isn’t one which I’ve ever seen. Relying on the tempo of growth, the
optimum author ratio could be nearer to 1:3 author to groups, however that’s nonetheless greater than the opposite fashions. - Writers can waste effort and get confused if they begin drafting earlier than the product is completed
“sufficient” to begin drafting. In case you doc each iteration of a characteristic circulation earlier than it’s finalized,
you may write the identical process a number of occasions. Typically these drafts allow you to get to probably the most environment friendly
and concise method of explaining one thing, however there’s additionally a threat {that a} author will get hooked up to an
incorrect psychological mannequin and the process finally ends up much less clear than it might need in any other case. - Can introduce single factors of failure. If each author is embedded in a selected crew, there’s a threat
that if that author goes on trip or quits, nobody else may have sufficient context to cowl for them
successfully. - The writers could be siloed and lack visibility into different initiatives on the firm. As a result of the writers
spend extra time with their engineering crew(s) than the documentation crew, this strategy takes further effort
to construct documentation crew cohesion and consistency throughout the writing types on the crew.
Which mannequin is one of the best?
It depends upon your priorities and circumstances!
In a really perfect world, I feel that the “I’m with the crew” mannequin is the one almost certainly to supply the
greatest documentation — however it’s additionally probably the most resource-intensive, and subsequently may not be probably the most
possible possibility for each group.
The “put out the newest hearth” mannequin can work effectively at an organization with low-complexity initiatives and constant
organization-wide procedures, making it potential to plug-and-play writers on demand to totally different initiatives.
Sadly, many initiatives that require documentation additionally profit from robust area experience and native
mission context, so this strategy is greatest suited to quick time period transition phases at an organization. After you
know what initiatives are going to stay round and wish writing dedication, you possibly can put money into a extra proactive
and embedded strategy just like the “I’m with the crew” mannequin.
For small corporations like a seed-stage startup, or one that’s nice at asynchronous communication, the
“throw it over the wall” strategy permits you to add documentation with out altering your core engineering
processes. In case you’re on the early stage the place you’re prioritizing shifting as quick as potential a lot of the
time, this strategy most likely is sensible.