Pleo Technical Writing Task
Rapid platform mastery demonstration: complete API documentation portal built in 9 hours using Stoplight (zero prior experience), showcasing OpenAPI 3.1 expertise, OAuth implementation, and professional developer documentation standards.
TECHNOLOGY STACK
Project Overview
Task Requirements
Create comprehensive API documentation and developer portal demonstrating technical writing capabilities, OpenAPI expertise, and ability to deliver professional results within tight time constraints using an unfamiliar platform.
Platform Selection & Constraints
- • Platform: Stoplight (zero prior experience)
- • Access Level: Free tier features only
- • Time Limit: 9 hours total delivery time
- • Deliverable: Complete API specification and documentation portal
- • Scope: Integration guides, flowcharts, and developer onboarding
Delivered Outcomes
Live Documentation Portal
The live demonstration showcases a complete API documentation experience with interactive testing, code generation, and comprehensive examples - all generated from a single OpenAPI specification.
Clarence Services API
Interact with Clarence the Dog via simple HTTP calls
API Structure & Authentication
Base URL
https://external.pleo.io/v3Authentication
OAuth 2.0 with clarence.actions scope
Supports both Authorization Code and Client Credentials flows
Documentation Features
- • Complete integration procedures and flowcharts
- • Interactive try-it-out functionality
- • Code examples in multiple languages
- • Comprehensive error handling scenarios
- • OAuth 2.0 setup and testing guides
Available Actions
/clarence/sitAsk Clarence to sitReturns confirmation if Clarence sits successfully.
Success Response (200)
{
"status": "ok",
"action": "sit",
"detail": "Clarence sits politely. Good boy!"
}Error Response (400)
{
"type": "clarence_asleep",
"message": "Clarence is asleep. Try again in a few minutes."
}/clarence/pawAsk Clarence to offer his pawChoose which paw using the side query parameter.
Query Parameters
side enum: "left" | "right" (required)Example Request
GET /clarence/paw?side=leftResponse Examples
{
"status": "ok",
"action": "paw",
"detail": "Clarence offers his left paw."
}/clarence/heelAsk Clarence to heelCommands Clarence to walk obediently beside you.
Request
No request body required
Requires OAuth 2.0 with clarence.actions scope
Success Response (200)
{
"status": "ok",
"action": "heel",
"detail": "Clarence heels at your side."
}Core Data Models
ActionResult Schema
status enum: "ok" (required)action string (required)detail string (optional)Error Schema
type string (required)message string (required)Rapid Platform Mastery: 9-Hour Challenge
The Challenge
Demonstrate technical writing and API documentation capabilities using Stoplight - a platform I had never used before - with a 9-hour time limit and access only to free tier features. The goal: prove I can rapidly learn and effectively leverage unfamiliar tools to deliver professional results.
Approach & Strategy
Rapid Learning (2 hours)
Platform exploration, feature mapping, and identifying optimal workflow for the constraint.
Strategic Design (3 hours)
OpenAPI 3.1 specification creation with creative but professional API concept (Clarence the Dog).
Documentation Development (4 hours)
Complete portal with integration guides, flowcharts, and comprehensive documentation structure.
Key Constraints & Solutions
Free Tier Limitations
No advanced features, limited customization. Solution: Focus on content quality and maximize basic feature utilization.
Zero Prior Experience
Never used Stoplight before. Solution: Systematic exploration and rapid iteration based on documentation patterns.
9-Hour Time Constraint
Tight deadline requiring efficiency. Solution: Front-load learning, focus on core deliverables, iterate quickly.
Technical Execution & Results
The final deliverable demonstrates comprehensive API documentation capabilities within platform constraints, showcasing ability to adapt quickly to new toolchains while maintaining professional standards and creative problem-solving.
What Was Delivered
Complete OpenAPI 3.1 Spec
Fully functional API specification with OAuth 2.0, comprehensive error handling, and realistic examples.
Integration Documentation
Step-by-step guides, flowcharts, and procedures for developer onboarding and implementation.
Interactive Portal
Public documentation site with try-it-out functionality and multi-language code examples.
Core Capabilities Demonstrated
Platform Agnostic Skills
- • Rapid tool evaluation and workflow optimization
- • OpenAPI specification design and architecture
- • Technical writing for developer audiences
- • Documentation structure and information architecture
Adaptability & Efficiency
- • Learning unknown platforms under time pressure
- • Working within constraint limitations effectively
- • Maintaining quality standards with limited resources
- • Creative problem-solving within technical boundaries
Implementation Insights
Design Decisions
Design-First Approach
Specification-driven development ensuring consistency between documentation and implementation.
Component Reusability
Shared schemas and examples across endpoints to maintain consistency and reduce duplication.
Comprehensive Examples
Rich examples covering edge cases, error scenarios, and realistic data patterns.
Best Practices Demonstrated
- • Semantic versioning for API evolution
- • Consistent error response formats
- • Comprehensive parameter validation
- • Clear authentication documentation
- • Rate limiting and quota guidance
- • Deprecation strategies and migration paths
Documentation Architecture & Future-Proofing
The specification was designed with extensibility and developer experience in mind, creating a foundation that supports advanced integrations and tooling even within the constraints of a 9-hour delivery window.
Built-In Features
- • Interactive try-it-out functionality with OAuth
- • Multi-language code examples (auto-generated)
- • Comprehensive error handling documentation
- • Integration flowcharts and step-by-step guides
SDK-Ready Architecture
- • Consistent naming conventions for code generation
- • Proper schema definitions enabling SDK creation
- • Structured for Postman collection export
- • OpenAPI 3.1 compatibility with modern toolchains
Strategic Design
The API specification structure anticipates common developer needs and tooling requirements, ensuring that when SDK generation or advanced integrations are needed, the foundation is already in place. This demonstrates forward-thinking documentation design within rapid delivery constraints.