Where to Start?

Where is the "Sweet Spot" for the Documentation resource injection point, regardless of the Methodology?

This is a "Reader's Digest" Condensed version of a longer TCPE Proof of Concept document about where the Documentation resource "Sweet spot" injection point should be, from a Technical Writer's perspective.

If you are interested in the full document, contact the Author.

Purpose

This document outlines the Documentation suggested injection points for Technical Writing (TW) resources into the Agile Development methodology. If you have any questions or feedback, please contact the author.

Scope

Engineering groups generally follow a Scrum-based Agile methodology based on a “X” week sprint calendar as part of the Software Life Cycle. Where there are multiple teams, each team may choose how to align to a commonly used two-week cycle with the calendar. Teams generally follow the same methodology with the same Agile rituals, Refinement standards, Estimation approach, and so on.

Exceptions

This document focuses on the Technical Content (Guides, Whitepapers, Use cases, etc.). It discusses common Agile Methodology components, but does not recommend specifics—just that Agile gets “practiced”.

Agile Rituals

Each team performs the following rituals in the course of the sprint. Each day of the sprint when there isn’t either a planning, refinement, review, or retro.

While two week sprints find themselves to be a common baseline in the Agile world; a Sprint can be any length—longer, but rarely shorter, in length.

Running a three week Sprint, for example, allows the insertion of more time and resources dedication to the content, for example, including a “Refinement” milestone mid-week in Week Two and Validation Review mid-week in Week Three of the sprint cycle.

Issue Types

Agile, as I understand it at a high level (I’m no SCRUM Master) contains the following components to be considered:

Epic

A container issue type for major initiatives. Epics should have a well-defined scope and criteria for completion. These are typically captured and documented during the initial Spike.

An epic is initially created with minimal high-level requirements that reflect the product or engineering roadmap.

Story

The typical format for capturing user value creation tasks. Traditionally, stories take a form similar to “As an X, I need/want Y so I can Z”. However, we are not so formal in our story format. The main thing is that stories are used to capture vertical slice features; delivering a story should deliver something useful to a stakeholder.

Bug

We track software defect reports separately from stories or tasks. A major bug might generate stories or tasks downstream, but the initial report should always be captured as a bug. Bugs are refined, planned, estimated, prioritized, and delivered the same as stories or tasks.

Task

Tasks are used to track work that is necessary but doesn’t have a clear relationship to a stakeholder result. A lot of non-functional work such as library upgrades, testing improvements, security enhancements, architecture refactoring, and so on may be captured as tasks.

Spike

Major projects are captured in epics which typically begin with a spike. The spike is a special time-boxed task with the following outcomes:

• A scope and requirements document
• Peer-reviewed architecture documentation
• Entire implementation effort outlined in high-level (8-13 point) stories
• First two sprints of stories well-factored (1-5 points), refined, and ready to be picked up
• Design comps as required to refine the work

Documentation Rituals

Based on estimates gathered from SMEs, Product Engineering, and Requirements or Specification documents, documentation, in a lot of scenarios, tends to be a more Hybrid or “Waterfall” process. Writing “docs“ is not a 1:1 match to coding a feature—it just takes more time to wordsmith a feature or service explanation—especially so if you are writing to an audience or Persona who is not a Power User or expert on the topic.

From a high level, the documentation process can be divided into the following components:

• Discovery
• Creation
• Validation
• Go to Market (GTM)
• Sustainment

Discovery

Discovery signifies the assignment of a technical writing resource to the project;. The product, at this point, ideally, will be more a list of planned features (especially for a new product) called out in a Requirements or Specifications document. When the preliminary walkthrough is complete, Documentation will build an outline with a bullet list of features and a high-level numbered list of steps to use the feature(s).

Creation

Creation phase content will be based on preliminary information provided by the Product management and Development teams as well as any available “poking around” the technical writer(s) can arrange. This will be hit and miss as stability of product is not a certainty.

This outline will be used to start the “fleshing out” with a small select group of internal users (ideally ones with a deep knowledge of the existing product or the goal of the new product). As the Creation progresses, their feedback will be used to expand the outline components.

At the end of the designated window, the content outline will be filled in more than the beginning of the Alpha process and be classified as a Creation Documentation Release Candidate (CRC) ready to be ingested into the Validation phase.

Validation

Validation brings about more stability of product and environment and will usually contain known (and unknown) bugs. Content is more robust, but by no means complete nor should it be assumed to be fully accurate, due to the above-mentioned known bugs.

Validation phase content will include an expanded user group with the invitation of moderate knowledge and new users to join a core of experienced Discovery resources.

It is also possible you could introduce external users (customers) into the process, but only after the appropriate NDA and other restricted legalities are dealt with.

As a rule, I do not ever suggest the inclusion of external (customer) users in the process as it can mislead regarding the final marketed product.

At the end of the Validation phase, the content should be a complete document with accuracy reflecting the state of the code itself. Any remaining bugs should be noted and rated

• Known-workaround available
• Known-no current workaround

Go To Market

Go for Market (GTM) occurs once the content has passed through the Creation and Validation phases.

• Project Sponsor has signed off
• Subject Matter Expert(s) have signed off
• The Product SME agrees the documentation reflects the product advertised functionality
• The Technical SME confirms the documentation reflects the product technical functionality
• Other Reviewers have signed off

The result is the GTM Release Documentation Candidate (Customer-facing).

Sustainment

Sustainment is all about Revisions once the content has been released. As published content, you have produced a starting point for the function and feature explanations for the end users.

Documentation is dynamic; it is not a “one and done” resource. Features are added or removed, outside elements, such as operating systems, hardware and software can affect features and functionality—which needs to then be identified, explained, and addressed within documentation.

Release Notes (Component Expansion)

Release Notes can be either standalone component or grouped within the Sustainment event. Release Notes are also flexible as far as how often they are generated. Depending on the release of Features or critical Bug Fixes, release dates can range from the following:

• Immediate (Critical Bug Fix or a highly coveted Feature Release)
• Bi-monthly (every two weeks)
• Monthly

Based on prior timeline examples, a “Sweet spot” seems to reside around the two-week mark. That allows a steady stream of perceived activity moving forward—even if there is nothing released or fixed within a particular Sprint.

Classic Models: Agile vs. Waterfall

While Agile and Waterfall are both methodologies that exist in project management, their use cases and core rules are extremely different. The main difference between Agile and Waterfall is that the Agile methodology is extremely flexible, whereas the Waterfall methodology is rigid.

The Agile methodology is team-driven and includes room for quick changes, edits, and room for stakeholder feedback throughout. On the other hand, the Waterfall approach is more traditional, with projects following a sequential approach that only involves feedback at the end of the project.

Agile Methodology

• Key points: High degree of flexibility and continuous evolution
• Requirements: Shorter deadlines, frequent check-ins, and a highly adaptable team with team members that can play various roles as needed
• Adaptability: Agile projects are able to adapt to unexpected changes and edits faster than most other project management methodologies, making them a great choice for software developers, product designers, and other teams dealing with high levels of uncertainty.
• Faster issue detection: Because Agile projects rely on delivering a functional product as quickly as possible, Agile teams can identify product issues faster than non-Agile teams that would only notice issues at the end during product delivery.
• More efficient: Agile teams are often more efficient and faster moving than non-Agile teams, as team members are encouraged to creatively solve problems and continuously improve through feedback and testing.
• Transitional difficulties: Teams migrating to the Agile methodology from more traditional methods, such as Waterfall, may find the transition challenging.
• Lack of documentation: In the Agile methodology, comprehensive project documentation isn’t as prevalent as in the Waterfall methodology, making it difficult to extract exact details, budget, and even communicate if teams aren’t mindful.
• Scope creep: Because the end goal is less definite than in other methodologies, Agile projects can be particularly susceptible to scope creep.

Waterfall Methodology

• Key points: Rigid structure and a sequential process
• Requirements: Highly structured team, a hands-on project manager, and a well-defined project plan
• Well documented: The Waterfall methodology relies on thorough documentation, making it easier to track project expenses and even replicate the project, if needed, in the future.
• Precise structure: Waterfall projects are predictable and follow an exact process, eliminating uncertainty and creating highly defined roles for team members.
• High visibility: Especially for teams that are accountable to external stakeholders, the Waterfall method provides a high level of visibility into project work at every phase, making it easy to update stakeholders on project progress.
• Limited client involvement: External clients and stakeholders that want a high level of involvement with project work might feel excluded from Waterfall projects that limit client involvement.
• Inflexible: The Waterfall method leaves little room for revisions or changes. Additionally, Waterfall projects have less capacity to adjust if circumstances suddenly change.
• Time-consuming: Compared to Agile teams, Waterfall projects move more slowly, especially during the project initiation stages, as they require much more in-depth documentation.

How to Choose Between Methodologies (or do we?)

Project Planning confirms the scenario is dynamic; what works, from a Methodology standpoint, for one project, may not be adequate for the next project. The “perfect world” would find every project works the same.

That’s obviously not going to happen. Teams could find themselves forced to switch between Agile and Waterfall. Hybrid then has the potential to smooth that bumpy path.

The Documentation Factor

Similar (and sometimes same) considerations apply in the Documentation ecosystem: One size rarely fits all. Factoring in the identified documentation requirements adds a level of complexity to determining the best Methodology to apply. Rarely though, does it get factored at the beginning and that complexity can rear its (sometimes) ugly head during the execution of the Project.

When to consider Agile Methodology

The Agile methodology embraces uncertainty, with ambiguous details and adaptability reigning.

Projects with high levels of uncertainty regarding time, budget, and resources are obvious candidates for the Agile methodology. In particular, technical teams favor Agile project management because of the flexibility.

When to consider Waterfall Methodology

The Waterfall method relies on sequential events with high levels of predictability. A wide variety of projects are good candidates for the Waterfall model, including projects with well-defined requirements, small or highly focused goals, projects that do not require a rigid timeline, and projects repeatable steps.

What about a Hybrid Methodology?

A Hybrid methodology is a combination of two or more project management methodologies to create a new or more fitting model for a project with unique requirements. This methodology can be applied over the whole project life cycle or only to particular parts of it.

Hybrid Methodology uses a technique where high-level project phases are planned with the Waterfall Methodology and the project tasks are done using an Agile Methodology.

Waterfall for planning

Apply the waterfall approach only for high-level deadlines, deliverables, and Documentation, based on the Doc Rituals identified above:

• Agree only on top-level things like final deadlines, milestones, deliverables, or classical project phases.
• Identify phases of a project where Agile can come in.

Agile for execution

Secondly, introduce Agile execution cycles for project tasks where it makes sense:

• Identify project types and “Size” them into tasks that are less than a day in length to complete.
• Create a prioritized work backlog from the project phases, goals, or other imbedded milestones.
• Research and structure iterations that are doable in 2- or 4-weeks blocks.
• Note: Experience has suggested that two weeks sprints are effective if the team has less experience and more “hands on” alignment needs exist.
• Plan the team work prior to the integration using backlogged, prioritized, items.
• Research, estimate, preliminarily assign task(s) to guarantee the plan for that sprint.
• Do a retrospective upon sprint end, identifying what went well and what can be improved.
• Capture metrics on how many tasks were completed (vs. Estimated) and how close to the estimate, for resources and targets, you were able to achieve.
• Use captured completion metrics to adjust your future planning.

Factors to consider when choosing a Methodology

Comparing methodologies, while not always straight forward, can be done due to the common aspects[1] across all styles.

Hardpoints: Regardless of Method

• What’s the scope of your project?
• Is there a hard deadline?
• Is the budget fixed or flexible?
• Do you have a project leader steering the ship?
• How does software development fit into the picture?
• Will your team work on more than one project at once?
• Does your team have experience with Agile? What about a knack for collaboration and self-organization?
• Can you count on your stakeholders to engage when needed?
• How do you maintain an open stream of communication?

[1] TeamHood’s Hybrid Project Management (https://teamhood.com/project-management-resources/hybrid-project-management/) Table comparison.

Aligning Methodologies and Documentation

Option 1: Aligning Documentation to Agile using Rituals

Documentation could follow the Rituals.

Planning:

1. List and describe ALL feature enhancements or fixes (Requirement or Specifications document).
2. Identify the list of online and legacy pages that should be updated or added.
3. Generate the list of feature content to be edited or added.
4. Create outline(s) identifying where to update or add feature content.

Refinement

1. Confirm that requirements and features are accurate.
2. Modify content outline additions or modifications based on feature refinement.
3. Draft all content covering all those new features (Requirements).

Review

1. Review all content covering all those new features.
2. Modify content additions or modifications based on feature review.

Retro

1. 1. Signoff on content.
2. 2. Retrospective (What was right/worked/wrong/rework/dropped from the feature list affecting documentation).

Option 2: Aligning Documentation using Agile Epics

Documentation could follow the Epic status.

For each Epic (project), follow these documentation steps:

1.  List and describe ALL feature enhancements or fixes (Requirement or Specifications document).
2. Identify the list of online pages that should be updated or added.
3. Generate the appropriate list of Google Doc to be edited.
4. Draft all content covering all those new features.

Option 3: Aligning Documentation to Hybrid Phases

Waterfall for planning

First of all, we will use the waterfall approach only for high-level deadlines and deliverables:

• Agree only on top-level things like final deadlines, milestones, deliverables, or classical phases:
• Discovery
• Creation
• Validation
• Go to Market (GTM)
• Sustainment
• Identify phases of a project where Agile can come in.

Agile for execution

Secondly, introduce Agile execution cycles for the project tasks

• Identify project work types and try to break them into tasks that are less than a day.
• Create a prioritized work backlog that fulfills the project phase or whole project goal/milestone.
• Agree to work in iterations (sprints) of 2 or 4 weeks. 2 weeks is good if the less experienced team and more alignment are required.
• Before each iteration, plan what the project team will work on by taking prioritized items from the backlog.
• Estimate every task so you know how many you can fit into a single sprint.
• At the end of every sprint, do a retrospective – what went well and what can be improved? Capture metrics on how many tasks and total estimation were completed.
• Use captured completion metrics to adjust your next sprint planning.

Summary

Aligning Agile, Waterfall, and Documentation Methodologies can be a challenge.

Documentation has been mostly associated with the Waterfall Methodology; partially due to the amount time to write, review, and publish the content.

Hybrid seems to be the strongest option: Code changes, feature changes UX changes—all effect the documentation—in many instances, more than it effects the actual Coding process.

A good example is the phrase:

                         “A picture is worth 1,000 words.”

When you go and change the UI, or the UX elements within a product, that affects all content: Your descriptions change, your screenshots change—just to name a few potential trouble spots.

Regardless of the Methodology choice, if you do not factor in Documentation, you are injecting a Risk and Issue scenario into your Project.

Using a Hybrid Methodology (Planning: Waterfall / Execution: Agile) offers a potential solution that should be explored as long as it aligns with the Dev/Engineering method of Project work.

Doing so means extra attention should be exercised regarding the Execution phases as Work tasks, while seemingly small scale in nature, could have profound effects on the Documentation deliverable. Proper scaling is a must.

Injection Points (suggested)

Regardless of the Sprint length, the "Sweet spot" injection point should be the Specification or Requirements content creation and sign off at the very beginning of the event. When the Requiremnts are signed off--even though they can shift during the Sprint window, enough outline material is avaiolable for the writer(s) to get started.