01 — The Problem
Written for the wrong reader
Cisco's original document explains VPN technology accurately — but for the wrong audience. It introduces SSL VPN, IPsec policies, and hub-and-spoke topologies without defining its reader or its scope.
A non-technical employee opening this page to connect to a company VPN will not find actionable guidance. Cisco's support portal contains over 46,000 configuration guides, all targeting IT professionals. No accessible guide exists for the remote employee who simply needs to connect.
01
No defined audience
The document assumes IT expertise without stating this. A non-technical reader has no way to know this guide is not for them.
02
Unexplained acronyms
SSL, IPsec, IKE, and MFA appear without definition. First use does not follow the Full Term (Acronym) convention.
03
No scope statement
The document does not state what it covers or what it does not cover, leaving the reader without orientation.
04
Passive voice throughout
"Data is encrypted" and "traffic is routed" obscure who acts and what the reader should do.
05
No What/Why/How structure
Concepts are introduced without explaining why they matter to the reader or what action follows.
06
No comparison table
Protocol differences are described in prose, making it impossible to scan and compare options quickly.
02 — Before & After
The same concept, rewritten
The original document introduces VPN without context for the reader's situation. The rewrite anchors the concept to something familiar and connects it immediately to a real task.
Original
"A VPN, or virtual private network, is an encrypted connection over the Internet
from a device to a network. The encrypted connection helps ensure that sensitive
data is safely transmitted. It prevents unauthorized people from eavesdropping
on the traffic and allows the user to conduct work remotely."
Rewritten
A VPN (Virtual Private Network) is an encrypted tunnel between your device and
your company's network. Think of it as a secure private road on the public
internet — your traffic travels through it invisibly to anyone outside.
Your company requires a VPN because it protects sensitive data — files, emails, internal systems — from being intercepted when you work outside the office.
Your company requires a VPN because it protects sensitive data — files, emails, internal systems — from being intercepted when you work outside the office.
The rewrite applies the Term → Class → Defining Characteristics definition
framework and anchors the concept to the reader's real situation before explaining the technology.
The troubleshooting section applies a structured Symptom → Cause → Solution format, replacing unstructured prose with scannable, actionable entries.
Original
"If you experience connection issues, check your internet connection and make
sure you have the correct server address. You may also need to check your
credentials or contact your IT department."
Rewritten
Symptom: "The VPN connection failed."
Cause: Incorrect server address entered.
Solution: Open Cisco Secure Client. Select the server address field and re-enter the address provided by your IT department exactly as written. Server addresses are case-sensitive.
Cause: Incorrect server address entered.
Solution: Open Cisco Secure Client. Select the server address field and re-enter the address provided by your IT department exactly as written. Server addresses are case-sensitive.
Each of the five troubleshooting entries follows the same structure, so readers can scan
by symptom without reading the full section.
03 — The Process
How I approached the rewrite
1
Defined the target audience
A non-technical remote employee who needs to connect to the company VPN without calling IT. Familiar with browsers and apps; has heard "VPN" but does not know what it is.
2
Identified six documentation failures
Mapped each failure to a specific technical writing principle: audience definition, acronym convention, scope statement, active voice, What/Why/How structure, and comparison tables.
3
Built a five-section outline around the reader's task flow
Structured around what the reader needs to do, not how the technology works: What is a VPN → Why your company requires it → How to install → How to connect → What to do if it fails.
4
Researched Cisco Secure Client 5.x
Verified step accuracy, platform differences between Windows and macOS, and MFA behavior to ensure the guide reflects the actual product experience.
5
Applied definition writing and anchoring analogies
Used Term → Class → Defining Characteristics for VPN, tunnel, and encryption. Each definition connects the concept to the reader's existing knowledge before introducing the technical details.
04 — Key Skills Demonstrated
What this project shows
Audience analysis and persona definition
Scope and non-scope definition
Plain-language definition writing
Step-by-step procedural writing
Technical research and accuracy verification
Structured troubleshooting documentation