Give me a structure for writing a documentation for a service running on an EC2 instance.
GPT-3.5
GPT-6 Astra
Here’s a practical documentation structure for a service running on an AWS EC2 instance. You can use it as a README or split it into separate architecture, deployment, and operations documents.
1. Service overview
- Service name and purpose
- Business functionality
- Owner/team and support contact
- Repository and related documentation
- Environments: development, staging, production
- Criticality and availability requirements
2. Architecture and dependencies
Describe how requests reach the service and which systems it depends on.
Include:
- Architecture or network diagram
- Application components and technologies
- Inbound traffic path: DNS → load balancer/reverse proxy → service
- Dependencies: databases, queues, caches, external APIs
- Ports and protocols
- Background jobs and scheduled tasks
Example:
Client → Route 53 → ALB → EC2 / application → RDS
└────→ S3
3. AWS infrastructure
Document the infrastructure for each environment.
| Item | Details |
|---|---|
| AWS account and region | Account ID, region |
| EC2 instance | Instance ID or discovery tags, instance type |
| Operating system | Distribution, version, AMI |
| Network | VPC, subnet, public/private placement |
| Security groups | Allowed traffic and purpose |
| IAM role | Attached role and required permissions |
| Storage | EBS volumes, mount points, encryption |
| Load balancer | Listener rules, target group, health checks |
| DNS and TLS | Hostnames, certificate management |
| Infrastructure as code | Repository and stack/module location |
If instances are replaceable, document how to identify the current instance rather than relying only on a fixed instance ID.
4. Access and security
- How to request access
- How to connect, preferably through AWS Systems Manager Session Manager
- SSH procedure, if applicable
- Required IAM permissions and operating-system accounts
- Privilege escalation rules
- Secrets storage and retrieval, such as Secrets Manager or Parameter Store
- OS and application patching responsibilities
- Credential and certificate rotation procedures
Do not include passwords, private keys, tokens, or secret values. Reference their approved storage locations instead.
5. Application configuration
Document where the application lives and how it is configured.
- Installation and working directories
- Runtime and dependency versions
- Configuration file locations
- Environment variables
- Secret references
- Service user and file permissions
- Configuration change and restart requirements
Example configuration table:
| Setting | Purpose | Required | Default | Source |
|---|---|---|---|---|
APP_PORT |
Application listening port | No | 8080 |
Environment file |
DATABASE_URL |
Database connection | Yes | — | Secrets Manager |
6. Deployment and rollback
Provide repeatable instructions covering:
- Prerequisites and required permissions
- Build and artifact creation
- Deployment method: CI/CD, configuration management, or manual process
- Configuration updates
- Database migrations, if applicable
- Service restart or replacement
- Post-deployment verification
- Rollback procedure and limitations
Include:
- Pipeline links
- Version/artifact naming conventions
- Expected downtime
- Approval requirements
- What to do if deployment fails
7. Service operation
Explain how the application is managed—for example, using systemd, Docker, or another supervisor.
For a systemd service:
# Check status
sudo systemctl status <service-name>
# Start / stop / restart
sudo systemctl start <service-name>
sudo systemctl stop <service-name>
sudo systemctl restart <service-name>
# Follow logs
sudo journalctl -u <service-name> -f
Also document:
- Service definition location
- Startup behavior after an EC2 reboot
- Graceful shutdown behavior
- Health and readiness endpoints
- Safe maintenance procedures
- Scheduled jobs and their management
Clearly identify commands that cause downtime.
8. Monitoring, logging, and alerting
- Log locations and CloudWatch log groups
- Log retention and sensitive-data handling
- Dashboard links
- Application metrics: error rate, latency, request volume
- Instance metrics: CPU, disk usage, memory, network
- Alert thresholds and notification destinations
- Health-check behavior
- On-call ownership and escalation
Note any required monitoring agent; memory and filesystem usage are not included in default EC2 metrics.
9. Data, backups, and recovery
- Where persistent data is stored
- Which local files are disposable
- Backup scope, schedule, retention, and encryption
- EBS snapshot or other backup procedures
- Restore instructions and verification steps
- Recovery time objective (RTO)
- Recovery point objective (RPO)
- Date and results of the last restore test
Explicitly state what survives an instance reboot, replacement, or termination.
10. Troubleshooting and incident runbooks
Provide symptom-based procedures.
| Symptom | Checks | Resolution/runbook |
|---|---|---|
| Service unavailable | Process status, logs, health checks, security groups | Link or steps |
| High latency | CPU/memory, dependency latency, request volume | Link or steps |
| Disk full | Filesystem usage, log growth, volume capacity | Link or steps |
| Database connection failure | Connectivity, credentials, connection limits | Link or steps |
| Service fails after reboot | Startup configuration, mounts, dependencies | Link or steps |
For each runbook, include:
- Symptoms and likely causes
- Diagnostic commands
- Safe mitigation steps
- Recovery verification
- Escalation criteria
11. Maintenance and capacity
- OS and runtime update schedule
- Maintenance windows
- Log rotation and cleanup
- Certificate renewal
- Instance resizing or scaling procedures
- Capacity limits and known bottlenecks
- Single points of failure and availability limitations
12. Documentation ownership and change history
- Document owner
- Last reviewed date
- Review frequency
- Significant infrastructure or operational changes
- Known issues and planned improvements
Recommended minimum: overview, infrastructure, access, configuration, deployment/rollback, operations, monitoring, and recovery. A new engineer should be able to use the documentation to find the service, access it safely, deploy it, diagnose a failure, and restore it.
What changed
The two answers imagine different readers. GPT-3.5 writes a setup tutorial: “selecting an Amazon Machine Image,” installing dependencies, then a “Conclusion” that summarizes the documentation, something no real operations doc needs. Astra writes for the engineer paged at 3 a.m. about a service that already exists. It covers rollback “procedure and limitations,” offers a symptom table that includes “Service fails after reboot,” and asks writers to “explicitly state what survives an instance reboot, replacement, or termination.” It also adds useful specifics, like the note that memory and filesystem usage are missing from default EC2 metrics, and a warning never to paste secrets into the doc.
Astra is long, but as a template its length mostly earns its place, since each heading answers a question someone will eventually ask. Still, GPT-3.5’s five tidy sections are a reasonable skeleton for a small side project, where twelve sections and an RTO line would be overkill. Astra’s closing “recommended minimum” partly concedes that.