01 — The Problem
The wrong order for the wrong reader
Rapyd's original document presented workflow steps before defining key concepts, included end-user UI walkthroughs irrelevant to developers, and contained a section whose title did not match its content.
A developer arriving from the Rapyd Checkout documentation would encounter undefined terms and misdirected content before reaching the API reference — the only part they actually needed.
01
Wrong information order
Workflow steps appeared before Payment Links were defined. A developer cannot follow a workflow for a concept they have not yet been introduced to.
02
Irrelevant content for the persona
The document included a Payment Link Example section — a UI walkthrough for end users. A backend developer writing API integration code has no use for this content.
03
Misleading section title
A section title did not match its content, sending the developer to the wrong place when scanning for specific information.
04
Misplaced reusability note
A note about Payment Link reusability appeared mid-workflow, interrupting the task flow at a point where it was not relevant.
05
Undefined technical term (FX)
The FX section introduced foreign exchange parameters without defining what FX means in this context or why a developer would use it.
02 — Before & After
The same content, restructured
The original document opens with a workflow step before defining what a Payment Link is. The rewrite opens with a scope statement and a precise definition.
Original opening
"To create a payment link, send a Create Payment Link request to Rapyd..."
Rewritten opening
This page explains Payment Link workflow and code. It does not explain Rapyd Checkout's workflow or code, which assumes you are already familiar with.
Definition: A Payment Link is a reusable hosted payment page that accepts fixed or customer-defined amounts — designed to be shared via SMS, WhatsApp, or email, rather than embedded in a specific transaction flow.
Definition: A Payment Link is a reusable hosted payment page that accepts fixed or customer-defined amounts — designed to be shared via SMS, WhatsApp, or email, rather than embedded in a specific transaction flow.
The rewrite applies scope and non-scope definition first, then introduces the concept before any action is required. The developer knows what they are building before they start.
The workflow section was restructured by actor — separating what you do, what the customer does, and what Rapyd does — to eliminate cognitive overload and clarify responsibility.
Original workflow
Single undifferentiated list mixing developer actions, customer actions, and Rapyd system actions — no indication of who performs each step.
Rewritten workflow
You: Generate a payment link via API request.
The customer: Clicks the link → sees amount → clicks Continue.
Rapyd: Redirects to payment page → sends webhook.
You: Notify the customer.
The customer: Clicks the link → sees amount → clicks Continue.
Rapyd: Redirects to payment page → sends webhook.
You: Notify the customer.
Actor-based workflow writing makes responsibility explicit. Each actor's steps are grouped together, so the developer immediately sees which steps require action on their side.
03 — The Process
How I approached the rewrite
1
Defined the target audience from context
Used the document's location in the Rapyd help center hierarchy to identify the reader: a backend developer already familiar with Rapyd Checkout, now integrating Rapyd Collect.
2
Identified five documentation failures
Mapped each failure to a specific principle: information order, audience relevance, section titling, content placement, and term definition.
3
Prioritized by severity and restructured
Ordered fixes by impact on the developer's task flow. Wrong information order and undefined terms were highest priority — they block understanding before the developer reaches the API reference.
4
Removed the Payment Link Example section
The section was relevant to end users, not developers. Removing it shortened the document and kept the focus on the developer's actual task.
5
Split the workflow by actor
Reorganized the workflow into three actor groups — You, The customer, Rapyd — so the developer immediately sees which steps require action on their side.
04 — Key Skills Demonstrated
What this project shows
Audience analysis and persona definition
Scope and non-scope definition
Information hierarchy restructuring
Plain-language term definition
Content removal decisions
Actor-based workflow writing