Skip to content

Latest commit

 

History

History
359 lines (261 loc) · 8.41 KB

technical-documentation.md

File metadata and controls

359 lines (261 loc) · 8.41 KB

Technical Documentation Writer

Description

Creates comprehensive technical documentation including user guides, API documentation, tutorials, and technical specifications. Adapts writing style and complexity level based on target audience and documentation type.

Usage

Provide the technical topic, target audience, and documentation type needed. Include any existing code, APIs, or technical details that need to be documented. Specify the level of technical detail required.

Prompt

Create technical documentation for the following:

### Documentation Type
[User Guide / API Documentation / Tutorial / Technical Specification / README / Other]

### Target Audience
[Developers / End Users / System Administrators / Technical Writers / Other]

### Technical Subject
[Describe what needs to be documented]

### Requirements
- **Scope**: [What should be covered and what should be excluded]
- **Format**: [Markdown / HTML / PDF / Wiki / Other]
- **Length**: [Brief overview / Comprehensive guide / Reference manual]
- **Technical Level**: [Beginner / Intermediate / Advanced / Mixed audience]

### Source Material

[CODE, APIs, SPECIFICATIONS, OR OTHER TECHNICAL CONTENT TO DOCUMENT]


### Special Requirements
- [Include examples / screenshots / diagrams]
- [SEO considerations for web documentation]
- [Translation requirements]
- [Accessibility standards]
- [Brand guidelines or style requirements]

Please structure the documentation with:
1. Clear introduction and purpose
2. Prerequisites and requirements
3. Step-by-step instructions where applicable
4. Code examples and use cases
5. Troubleshooting section
6. Reference materials and links

### Additional Context
[Any background information, existing documentation to reference, or specific pain points to address]

Example Input

### Documentation Type
API Documentation

### Target Audience
Frontend developers integrating with our REST API

### Technical Subject
User authentication and profile management API

### Requirements
- **Scope**: Authentication endpoints, profile CRUD operations, error handling
- **Format**: Markdown for developer portal
- **Length**: Comprehensive reference with examples
- **Technical Level**: Intermediate developers familiar with REST APIs

### Source Material
```python
# Authentication endpoints
@app.route('/api/auth/login', methods=['POST'])
def login():
    email = request.json.get('email')
    password = request.json.get('password')
    # Authentication logic here
    return jsonify({'token': jwt_token, 'user': user_data})

@app.route('/api/auth/logout', methods=['POST'])
def logout():
    # Logout logic
    return jsonify({'message': 'Logged out successfully'})

# Profile endpoints
@app.route('/api/profile', methods=['GET'])
@jwt_required()
def get_profile():
    user_id = get_jwt_identity()
    # Get user profile
    return jsonify(user_profile)

@app.route('/api/profile', methods=['PUT'])
@jwt_required()
def update_profile():
    # Update profile logic
    return jsonify(updated_profile)

Special Requirements

  • Include curl examples for each endpoint
  • Show both success and error response formats
  • Include rate limiting information

## Example Output
```markdown
# User Authentication & Profile API

## Overview
This API provides endpoints for user authentication and profile management. All authenticated endpoints require a valid JWT token obtained through the login process.

## Base URL

https://api.yourapp.com/v1


## Authentication
This API uses JWT (JSON Web Tokens) for authentication. Include the token in the Authorization header:

Authorization: Bearer <your_jwt_token>


## Rate Limiting
- **Unauthenticated endpoints**: 100 requests per hour per IP
- **Authenticated endpoints**: 1000 requests per hour per user

---

## Authentication Endpoints

### Login
Authenticate a user and receive a JWT token.

**Endpoint:** `POST /api/auth/login`

**Request Body:**
```json
{
  "email": "user@example.com",
  "password": "securepassword123"
}

Success Response (200):

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "id": 123,
    "email": "user@example.com",
    "name": "John Doe",
    "created_at": "2023-01-15T10:30:00Z"
  }
}

Error Response (401):

{
  "error": "Invalid credentials",
  "code": "INVALID_CREDENTIALS"
}

cURL Example:

curl -X POST https://api.yourapp.com/v1/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "securepassword123"
  }'

Logout

Invalidate the current JWT token.

Endpoint: POST /api/auth/logout

Headers:

  • Authorization: Bearer <token> (required)

Success Response (200):

{
  "message": "Logged out successfully"
}

cURL Example:

curl -X POST https://api.yourapp.com/v1/api/auth/logout \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Profile Endpoints

Get Profile

Retrieve the authenticated user's profile information.

Endpoint: GET /api/profile

Headers:

  • Authorization: Bearer <token> (required)

Success Response (200):

{
  "id": 123,
  "email": "user@example.com",
  "name": "John Doe",
  "bio": "Software developer passionate about APIs",
  "avatar_url": "https://cdn.yourapp.com/avatars/123.jpg",
  "created_at": "2023-01-15T10:30:00Z",
  "updated_at": "2023-06-20T14:22:00Z"
}

cURL Example:

curl -X GET https://api.yourapp.com/v1/api/profile \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Update Profile

Update the authenticated user's profile information.

Endpoint: PUT /api/profile

Headers:

  • Authorization: Bearer <token> (required)
  • Content-Type: application/json

Request Body:

{
  "name": "Jane Doe",
  "bio": "Senior software engineer with 5+ years experience"
}

Success Response (200):

{
  "id": 123,
  "email": "user@example.com",
  "name": "Jane Doe",
  "bio": "Senior software engineer with 5+ years experience",
  "avatar_url": "https://cdn.yourapp.com/avatars/123.jpg",
  "updated_at": "2023-06-21T09:15:00Z"
}

cURL Example:

curl -X PUT https://api.yourapp.com/v1/api/profile \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Jane Doe",
    "bio": "Senior software engineer with 5+ years experience"
  }'

Error Codes

Code HTTP Status Description
INVALID_CREDENTIALS 401 Email or password is incorrect
TOKEN_EXPIRED 401 JWT token has expired
TOKEN_INVALID 401 JWT token is malformed or invalid
VALIDATION_ERROR 400 Request data validation failed
RATE_LIMIT_EXCEEDED 429 Too many requests
INTERNAL_ERROR 500 Server encountered an unexpected error

Troubleshooting

Common Issues

"Invalid credentials" error

  • Verify email and password are correct
  • Ensure email is properly formatted
  • Check if account exists and is active

"Token expired" error

  • Obtain a new token using the login endpoint
  • Implement token refresh logic in your application

Rate limiting errors

  • Implement exponential backoff in your requests
  • Cache responses when possible to reduce API calls
  • Contact support if you need higher rate limits

Contact Support

For API issues or questions:


## Variations
- **Quick Reference**: Create concise reference cards or cheat sheets
- **Tutorial Style**: Step-by-step learning-focused documentation
- **Troubleshooting Guide**: Focus on common problems and solutions
- **Migration Guide**: Document how to upgrade or migrate between versions

## Tips
- Always include practical examples and code snippets
- Structure information hierarchically with clear headings
- Include both happy path and error scenarios
- Use consistent formatting and terminology throughout
- Add visual aids like diagrams or screenshots when helpful
- Keep the target audience's expertise level in mind

## Related Prompts
- `code-review.md` - For improving code before documenting it
- `architecture-planner.md` - For documenting system architecture
- `email-templates.md` - For creating documentation distribution emails

## Tags
`technical-writing` `documentation` `api-docs` `user-guides` `tutorials` `writing`