The Brief
StepSecurity provides a security platform for hardening CI/CD pipelines and GitHub Actions infrastructure — a complex, developer-facing product where unclear documentation creates real security risk for users. Misconfigured pipelines and missing context around security controls aren’t just frustrating; they leave organisations exposed.
I was brought in to lead a full documentation refresh and migration across three key workstreams: the main StepSecurity documentation suite, the Harden Runner README, and the GitHub Actions Goat README.
The challenge with CI/CD security documentation is precision. Every configuration option, every permission scope, every recommended hardening step needs to be accurate — because the reader is relying on it to make a security decision, not just a product decision.
What I Built
A coordinated documentation refresh across three distinct surfaces:
- Main Documentation Suite — Reviewed, restructured, and rewrote the StepSecurity docs to improve clarity, consistency, and navigability for developers evaluating and implementing the platform
- Harden Runner README — The README serves as both product introduction and technical reference for one of StepSecurity’s core tools; rewrote it to give developers the context they need to understand what Harden Runner does, why it matters, and how to integrate it correctly
- GitHub Actions Goat README — GitHub Actions Goat is a deliberately vulnerable CI/CD environment used for security training; documented the project clearly for contributors, educators, and security teams using it to understand real-world attack patterns
Approach
Security documentation requires a different register than standard developer docs. The reader is often making a trust decision — deciding whether to add a tool to their pipeline, grant it permissions, or recommend it to their security team. That means the writing has to be precise, the examples accurate, and the threat context clear without being alarmist.
My process across all three workstreams:
- Audit — Assessed existing content for gaps, inaccuracies, and structural issues before touching anything
- Rewrite for clarity — Simplified dense technical content without removing necessary precision
- Structure for different entry points — Different readers arrive at the same docs for different reasons; the structure needs to work for all of them
- Migration — Managed content across GitBook and Docusaurus, ensuring nothing was lost in the transition and the tooling matched each surface’s requirements
Results
The refreshed documentation suite gives StepSecurity a cleaner, more credible developer-facing presence — where documentation accuracy directly supports user trust in a security product. The Harden Runner and GitHub Actions Goat READMEs are now clear technical resources that reflect the quality of the underlying tools.