Case Study: Designing an Upstream Documentation Workflow

This case study shows how an upstream documentation workflow can be designed to capture and structure knowledge before it is lost in product and engineering handoffs.

It demonstrates how Jira automation, structured discovery, and content planning can turn fragmented upstream inputs into a coordinated documentation system that aligns technical writing, UX writing, and engineering work.

Context

This workflow models how a content team can operate upstream—before drafting begins—to stay tightly coupled with product and engineering.

The example uses Wayfarer, a B2B SaaS company with two products:

• Wayfarer Connect (API-first booking and supplier platform)
• Wayfarer Desk (agency operations platform)

The Content Experience team supports both products across developer docs, user documentation, and in-product content.

This workflow focuses specifically on the upstream phase of the documentation lifecycle:

intake → discovery → planning

This represents a structured upstream workflow in a mature content organization.

Problem Statement

In many product organizations:

• Content is brought in too late
• Jira and documentation systems are disconnected
• PRDs and related technical specs don’t consistently translate cleanly into documentation work
• Documentation scope is unclear until drafting begins
• Knowledge is fragmented across tools (Jira, Confluence, Slack)
• API design specs and engineering artifacts are inconsistently shared with content teams, leaving API doc writers dependent on SME interviews to reconstruct what the spec already contains

This leads to reactive documentation, rushed release notes, and gaps in user understanding.

Design Goals

This workflow is designed to:

• Couple documentation work tightly with product and engineering
• Reduce manual intake and coordination work
• Standardize documentation impact assessment
• Make documentation work visible, traceable, and trackable in Jira
• Enable earlier involvement of content in feature development
• Treat documentation as a system of knowledge flow—not just deliverables
• Account for different upstream knowledge sources depending on documentation type (end-user vs API/developer)

System Overview

Inputs

• Product Requirements Documents (PRDs)
• API technical specifications
• Engineering epics and stories
• Design mocks and UX flows
• Doc Request issues (ad hoc requests from support, UX, internal teams)

Inputs vary depending on documentation type. End-user and UX-aligned content is typically driven by PRDs and design artifacts, while API and developer documentation relies more heavily on technical specifications, backend implementation details, and engineering workflows.

System

• Jira (work tracking, automation, and integration point for engineering discussions)
• Confluence (knowledge artifacts)
• AI tools (summarization, question generation)
• Github (API spec review and PR-level contract visibility)

Outputs

• Jira: Doc Impact epics (product/engineering-driven, release work)
• Jira: Documentation tasks (linked to Doc Request task or Doc Impact epic)
• Confluence: Source Material Notes
• Confluence: SME Interview Notes
• Confluence: Documentation Content Plans (release-level)
• Jira: Structured documentation work items aligned to engineering

Workflow Overview

UX Writer Workflow

1. Design team kicks off feature design and opens Design Epic
2. UX writer opens UX Copy Epic → links to Design Epic and release Fix Version
3. UX writer joins design reviews → assesses copy needs (flows, microcopy, empty states, error messages, onboarding)
4. UX writer creates stories under UX Copy Epic for each copy need identified
5. UX writer iterates on copy alongside design — participates in design critiques and revisions
6. UX writer documents copy decisions with rationale (decision log, Confluence note, or Jira comments)
7. UX copy finalized → handed off to design and engineering for implementation
8. ⬇ MERGE POINT 1: Content Alignment — UX writer shares finalized or in-progress copy decisions with TWs before source review begins (sync meeting or shared artifact)
9. UX writer remains available through TW source review for terminology and intent questions

Technical Writer Workflow

1. Technical Publications team kickoff meeting for upcoming release
2. Product creates Epic and PRD
3. Automation generates Doc Impact Epic → links to Engineering Epic and release Fix Version → assigns TW
4. Senior TW performs light source scan — reads PRD for intent, scope, and feasibility
5. Senior TW performs intake triage → updates Level of Effort, Components, Doc Type
6. ⬆ MERGE POINT 1: Content Alignment — TW receives UX copy decisions before formal source review
7. Senior TW formally reviews PRD, design mocks, and engineering tickets → records Source Review Notes
8. Senior TW sets status to Approved → triggers task creation for Senior TW and TW II (if applicable)
9. TWs meet to align scope and timing for all release work
10. TWs conduct SME interviews
11. TWs create Documentation Content Plan (release-level)
12. TWs create final work items and align them to engineering

Non-Release Intake (Doc Request Workflow)

1. Any team creates a Doc Request issue in Jira
2. Request includes source material, context, and doc type needed
3. Automation or notification sends request to relevant Tech Pubs Slack channel
4. Technical writer reviews and triages request
5. Writer determines scope:
   • Small → direct task creation
   • Medium/Large → follow discovery workflow (Source Review → SME → optional Content Plan)

This ensures documentation work is defined before drafting begins, with clear processes, responsibilities, and explicit merge points between UX writing and technical writing.

System Components

Jira Data Model

Custom fields enable structured intake and planning:

• Documentation Impact (trigger for Doc Impact epic generation)
• Customer Impact
• PM Owner
• Engineer Owner
• Doc Type Needed
• Doc Audience
• Product
• Components
• Target Release
• All Assigned Writers
• Level of Effort

These fields ensure documentation requirements are captured at the same level as product requirements, while some fields (such as Doc Audience, All Assigned Writers, and Level of Effort) are used specifically for internal content team tracking and planning.

Automation Layer

Key automations:

Epic → Doc Impact Epic

• Trigger: Documentation Impact = Yes
• Action: Create Doc Impact epic in Tech Pubs space
• Map fields from source epic
• Assign default writer based on product

Approval → Task Generation

• Trigger: Doc Impact epic marked Approved
• Action: Create tasks for each assigned writer

This reduces manual coordination and ensures consistency.

Doc Request → Slack Notification

• Trigger: Doc Request created
• Action: Send notification to relevant Tech Pubs Slack channel
• Writers review and triage request

Ensure visibility of non-release work and prevent requests from being lost

Slack → Jira (Conversation Traceability)

• Enable Jira Cloud app in Slack to save Slack messages directly to Jira work items
• Notify writers when new work item created in Jira
• Writers attach relevant Slack conversations to the corresponding Jira item
• Capture follow-up clarifications, decisions, and edge cases alongside the work item

Preserve ephemeral discussions, improve traceability, and ensure important context isn’t lost across tools.

Confluence Layer

Structured templates support discovery and planning:

• Source Review Notes
• SME Interview Notes
• Documentation Content Plan (release-level)

These templates turn scattered knowledge into structured artifacts, with clear separation of purpose:

• Source Review Notes capture initial understanding from PRDs, design mocks, and engineering artifacts — identifying intent, scope, gaps, and early assumptions before SME validation.
• SME Interview Notes capture feature-level understanding — what changed, why it matters, how it behaves, and initial content implications for a single feature.
• Documentation Content Plan consolidates those inputs across multiple features into a release-level plan — what content will be created or updated, who owns it, and how work is organized and executed.

This separation ensures that feature-level discovery does not get conflated with release-level planning.

AI Layer

AI supports the upstream workflow in three ways:

• Documentation engineering support: creating and maintaining structured templates for Source Review Notes, SME Interview Notes, and the Documentation Content Plan as a shared team responsibility in the absence of a dedicated documentation engineer role.
• Writers summarize conversations: writers use AI tools such as Zoom AI summaries or Slack AI summaries to condense SME interviews and follow-up discussions into usable notes.
• Writers structure interview findings: writers use ChatGPT, Claude, or similar tools to turn Zoom AI summaries, Slack AI summaries, linked Slack threads in Jira, Jira comment threads, and follow-up notes into draft answers within the SME Interview template for review.

The AI layer also helps convert scattered upstream knowledge into structured discovery inputs, but it isn’t required for the Documentation Content Plan itself. The assessment relies primarily on writer judgment, synthesis, and decision-making based on validated inputs.

Additionally, Documentation Engineering can create a reusable prompt template (stored as a Markdown artifact) that guides writers in how to input Zoom summaries, Slack summaries, and Jira discussions and map them into the SME Interview template. This ensures consistency in how AI is used and reduces variability in output quality across writers.

Example: SME Interview Structuring Prompt (Markdown)

# Goal

Map raw conversation summaries into structured SME Interview Notes capturing feature behavior, risks, and content implications.

# Inputs

Provide any of the following (paste below):

- Zoom AI meeting summary

- Slack thread summaries or excerpts

- Jira ticket comments

- Personal notes from SME conversations

# SME Interview Template Questions

Fill answers under each section using the inputs. If information is missing, mark as "Unknown".

## Product

- What problem is this solving?

- Who is the primary audience?

- Is this required or optional behavior?

- What changes from the user’s perspective?

- Which products or parts of a product does this touch?

## Workflow

- What new task can users do now?

- What old workflow no longer works the same way?

- What choices or constraints do users need to understand?

- What configuration differences matter?

## Technical

- What changed in the system?

- What changed in the API contract, payloads, response behavior, or error handling?

- Are any fields deprecated?

- Are there rollout conditions or backward-compatibility limits?

## Risk

- What is most likely to confuse users?

- What is likely to break existing customer implementations?

- Are there market/supplier exceptions?

- Are there known edge cases?

## Release

- When is this shipping?

- Is it behind a feature flag?

- Is it GA, beta, limited release, or customer-specific?

# Instructions

- Use only the provided inputs; don't invent details.

- Consolidate duplicate or conflicting statements and flag inconsistencies.

- Prefer concise, factual answers (1–3 sentences each).

- If multiple sources disagree, note the discrepancy under the answer.

# Output Format

Return a clean, filled version of the SME Interview template with headings and bullet points.

Detailed Workflow

Phase 0: Non-Release Intake (Doc Request)

• Doc Request issue is created by any team
• Notification sent to relevant Tech Pubs Slack channel
• Writer reviews request and determines scope
• If needed, converts to standard workflow (Source Review → SME → Content Plan)

Phase 1: Intake Automation

• Product creates an epic with PRD
• Documentation Impact field is set
• Automation creates Doc Impact epic in DOCS space
• Fields are mapped and writer is assigned

Owner: Jira automation + Senior Technical Writer (review)

Phase 2: Intake Triage

• Assigned writer reviews PRD and epic
• Updates fields (doc type, components, effort, timeline)
• Identifies additional writers if needed

Owner: Senior Technical Writer

Phase 3: Approval and Task Generation

• Writer updates Doc Impact epic status to Approved
• Automation generates tasks for all assigned writers
• Initial tasks are created early for visibility and ownership, and are refined after discovery

Owner: Senior Technical Writer + Jira automation

Phase 4: UX Alignment (Pre-Discovery)

• UX writer shares finalized or in-progress copy decisions
• Technical writers review UX context before formal source review
• Terminology, intent, and workflow language are clarified early

Purpose: Ensure documentation reflects actual product language and intent from the start

Phase 5: Source Review

• Writers review PRD, API specs, design mocks, and engineering tickets
• Record findings in Source Review Notes
• Identify gaps and unclear areas

For API and developer documentation, source review also includes the API design spec, spec diffs or changelogs, and relevant GitHub PRs. The API spec is treated as the authoritative input for contract behavior — the PRD describes intent, the spec describes what the API will actually do.

Artifacts: Source Review Notes

Phase 6: Team Alignment

• Writers meet to align on scope, ownership, and timing

Owner: Content team

Phase 7: SME Interviews

• Conduct SME interviews to clarify feature behavior
• Capture edge cases, constraints, and workflows
• Link relevant Slack threads to the Jira epic or task to preserve follow-up discussions and decisions
• Record structured notes using template

Artifacts: SME Interview Notes

Phase 8: Documentation Content Plan (Release-Level)

• Writers consolidate inputs from SME Interview Notes and Source Review Notes across all relevant features
• Define what content needs to change across the release
• Identify audiences, channels, and ownership
• Determine dependencies and timing across work items
• Estimate scope at a release level (not per feature)

Artifact: Documentation Content Plan

Phase 9: Work Structuring

• Create documentation tasks in Jira
• Align tasks to engineering stories where possible
• Break tasks into subtasks based on feature behavior
• Add additional tasks as needed

Artifacts

Process Artifacts

• Doc Impact epic
• Source Review Notes
• SME Interview Notes
• Documentation Content Plan

Output Artifacts

• Documentation Plan
• Jira documentation tasks
• Release note inputs

Example: Connect Reissue Workflow Update

For the Connect reissue workflow update, a product epic is created in Jira and linked to the June 2026 release.

• Automation generates a Doc Impact epic and assigns it to Kemi (Senior Technical Writer, Connect)
• Kemi reviews the PRD and identifies impact across:
  • Connect web app users
  • Enterprise API users
  • Internal support teams
• Kemi adds Arya, Senior UX Writer, to All Assigned Writers due to UI impact

Kemi proceeds with discovery:

• Reviews PRD, design mocks, and engineering tickets
• Conducts SME interviews with product and engineering
• Captures feature behavior, risks, and edge cases in SME Interview Notes

Based on discovery, Kemi creates the Documentation Content Plan for the release:

• Identifies required updates across help docs, API docs, and release notes
• Defines affected audiences and content areas
• Aligns work across multiple features in the release

Kemi then structures the work in Jira:

• Refines auto-generated tasks
• Aligns tasks to engineering stories
• Creates additional tasks where needed

Example tasks:

• Update reissue workflow steps to include eligibility checks
• Add eligibility state explanations for API consumers

What This Enables

• Earlier content involvement in product development
• Clear alignment between documentation and engineering work
• Reduced ambiguity in documentation scope
• Scalable intake process
• Better cross-functional visibility

Tradeoffs and Limitations

• Requires consistent Jira usage across teams
• Depends on PRD quality and completeness
• Automation rules require maintenance
• Not all work fits cleanly into epic-based workflows

Reusable Pattern

This workflow can be adapted by:

• Defining a documentation intake trigger in Jira
• Creating a standardized Doc Impact artifact
• Using templates for discovery and planning
• Aligning documentation work to engineering work items

It is designed to scale across products, teams, and release models.