| sidebar_position | 13 |
|---|
Docs are living systems.
Keep DevX relevant over time. Developer experience degrades without active maintenance and evolution.
Run quarterly developer satisfaction surveys:
Key Questions:
## Developer Satisfaction Survey
### Onboarding (1-5 scale)
- How easy was it to set up your local environment?
- How long did it take to make your first commit?
- How well did documentation prepare you?
### Daily Workflow (1-5 scale)
- How often are you blocked by slow CI?
- How confident are you deploying to production?
- How easy is it to find answers to questions?
### Tools & Platform (1-5 scale)
- How satisfied are you with internal tools?
- How much time do you spend on toil vs. value work?
- How well do monitoring tools help you debug issues?
### Open Feedback
- What slows you down the most?
- What's one thing we should improve?
- What's working well that we should keep?Analyze Results:
- Track trends over time
- Compare scores across teams
- Prioritize lowest-scoring areas
- Share results transparently
Sources:
Capture feedback from team retrospectives:
## Retro Template
### What Went Well ✅
- Fast PR reviews this sprint
- New deployment pipeline saved time
### What Didn't Go Well ❌
- Flaky tests blocked 3 PRs
- Staging environment was down for 2 days
### Action Items 🎯
- [ ] Fix top 5 flaky tests (@alice, by next sprint)
- [ ] Set up staging environment monitoring (@bob, this week)Aggregate Themes:
Track recurring issues across multiple retrospectives:
| Issue | Frequency | Priority |
|---|---|---|
| Flaky tests | 8 retros | High |
| Slow CI | 5 retros | Medium |
| Unclear docs | 4 retros | Medium |
Sources:
Slack Channel: #devx-feedback
Purpose: Quick feedback on developer experience
Examples:
- "The new CLI saved me 30 minutes today 🎉"
- "Deployment docs are outdated for the new process"
- "Can we add autocomplete to the internal API?"
SLA: Acknowledged within 24 hoursOffice Hours:
- Weekly 30-minute open session
- Anyone can drop in with questions/feedback
- Record sessions for asynchronous viewing
Sources:
Track the four key metrics:
| Metric | Target | Measurement |
|---|---|---|
| Deployment Frequency | Multiple per day | CI/CD logs |
| Lead Time for Changes | < 1 day | Time from commit to production |
| Change Failure Rate | < 15% | Failed deployments / total deployments |
| Time to Restore Service | < 1 hour | Incident duration |
Example Dashboard Query:
-- Deployment frequency (last 30 days)
SELECT
DATE(deployed_at) as date,
COUNT(*) as deployments
FROM deployments
WHERE deployed_at > NOW() - INTERVAL '30 days'
AND environment = 'production'
GROUP BY DATE(deployed_at);
-- Lead time for changes
SELECT
AVG(EXTRACT(EPOCH FROM (deployed_at - committed_at)) / 3600) as avg_hours
FROM deployments
WHERE deployed_at > NOW() - INTERVAL '30 days';Sources:
Measure developer experience dimensions:
1. Speed (Feedback Loops)
- Time to run tests locally: < 5 min
- Time to get CI feedback: < 15 min
- Time to get code review: < 24 hours
- Time to deploy to production: < 1 hour
2. Effectiveness (Ability to Complete Work)
- % of time spent on new features vs. maintenance
- % of developers who feel productive
- % of tasks completed without blockers
3. Quality (Standards & Best Practices)
- Test coverage: > 80%
- Linting pass rate: 100%
- Code review approval rate: > 95%
- Production incident rate: < 1 per week
4. Satisfaction (Developer Happiness)
- Developer satisfaction score: > 4/5
- Would recommend company to other developers: > 80%
- Intent to stay: > 90%
Sources:
Each team owns their documentation:
docs/
├── api-gateway/ # Owned by Platform team
├── auth-service/ # Owned by Identity team
├── payment-processing/ # Owned by Payments team
└── shared/ # Owned by DevX team
├── onboarding/
├── architecture/
└── runbooks/
Ownership Responsibilities:
- Keep docs up to date: Update within 1 week of changes
- Review contributions: Respond to PRs within 48 hours
- Monitor feedback: Address confusion in docs
- Quarterly review: Validate accuracy every 3 months
Sources:
Treat documentation like code:
✅ DO:
- Version control all docs
- Require code review for doc changes
- Run linters on Markdown
- Test code samples automatically
- Deploy docs with CI/CD
❌ DON'T:
- Use wikis for critical docs (hard to version)
- Skip review for "minor" doc changes
- Let docs diverge from code
- Manually update multiple copies
Example CI Check:
:::tip Pin real workflow refs with Ratchet This example uses readable tags for clarity. In a real repository, run Pin workflow refs with Ratchet on your workflow files and commit the rewritten SHA pins. :::
# .github/workflows/docs.yml
name: Documentation
on: [pull_request]
jobs:
lint-docs:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
# Lint markdown
- uses: DavidAnson/markdownlint-cli2-action@v13
with:
globs: "docs/**/*.md"
# Check for broken links
- uses: gaurav-nelson/github-action-markdown-link-check@v1
with:
folder-path: "docs"
# Test code samples
- run: npm run test:docsSources:
1. Identify Problem
Document the pain point:
## Problem
Developers spend 2-3 hours setting up local environment.
## Impact
- New developers lose productive time
- Inconsistent environments cause bugs
- High frustration in onboarding surveys
## Evidence
- Onboarding survey: 2.3/5 satisfaction
- Average setup time: 2.5 hours (measured across 10 new hires)2. Propose Solution
## Proposed Solution
Create automated setup script that:
- Detects OS and installs correct tools
- Sets up pre-commit hooks
- Starts local infrastructure (Docker)
- Runs health checks
## Expected Outcome
- Setup time: < 30 minutes
- Onboarding satisfaction: > 4/5
## Effort Estimate
- Development: 2-3 days
- Testing: 1 day
- Documentation: 1 day3. Get Feedback
- Post in #devx channel
- Present in team meeting
- Create RFC for large changes
4. Implement & Measure
- Build the improvement
- Measure impact
- Iterate based on feedback
Sources:
Just do it:
- Fix broken link in docs
- Add missing example
- Update outdated screenshot
- Improve error message
Create PR → Get review → Merge
No formal proposal needed for small fixes.
Sources:
Track all improvements to developer experience:
# DevX Changelog
## 2024-01-28
### Added
- 🚀 Automated local environment setup script
- 📊 DORA metrics dashboard in Grafana
- 🔍 Code search in developer portal
### Changed
- ⚡ Reduced CI time from 20min to 12min (parallelized tests)
- 📝 Updated onboarding guide with new team structure
### Fixed
- 🐛 Fixed flaky test in payment-service
- 🔧 Resolved staging environment connectivity issues
### Deprecated
- ⚠️ Legacy deployment script (use `hk deploy` instead)
- ⚠️ Manual secret management (migrate to 1Password)
## 2024-01-15
### Added
- 🎯 Feature flag system with LaunchDarkly
- 📚 ADR template and process
...Distribution:
- Post monthly summary in #engineering
- Include in company newsletter
- Reference in onboarding materials
Sources:
Share upcoming DevX improvements:
| Quarter | Theme | Key Initiatives |
|---|---|---|
| Q1 2024 | Onboarding | Automated setup, improved docs, mentorship program |
| Q2 2024 | CI/CD Speed | Parallel tests, incremental builds, better caching |
| Q3 2024 | Observability | Distributed tracing, better error messages, runbooks |
| Q4 2024 | Developer Portal | Unified docs, API catalog, self-service tools |
Prioritization Criteria:
- Impact: How many developers affected?
- Effort: How much work required?
- Pain: How much friction does it cause?
- Alignment: Does it support company goals?
Score: (Impact × Pain) / Effort
Sources:
"Enable every developer to ship high-quality code confidently and efficiently."
- Maintain golden paths: Keep scaffolding and templates updated
- Improve tooling: Build and maintain internal tools
- Monitor metrics: Track DORA and DX Core 4
- Gather feedback: Run surveys and office hours
- Evangelize best practices: Share knowledge and success stories
- Developer-centric: Build for developers, with developers
- Measure impact: Data-driven decisions
- Iterate quickly: Ship small improvements frequently
- Enable autonomy: Self-service over tickets
- Document everything: No tribal knowledge
Sources:
# Q1 2024 DevX Review
## Metrics
| Metric | Target | Actual | Status |
| -------------------- | -------- | ------- | ------ |
| Deployment Frequency | 10/day | 12/day | ✅ |
| Lead Time | < 1 day | 8 hours | ✅ |
| MTTR | < 1 hour | 45 min | ✅ |
| Dev Satisfaction | > 4/5 | 4.2/5 | ✅ |
## Achievements
- Reduced CI time by 40%
- Onboarding time: 3 hours → 1 hour
- Launched developer portal
## Challenges
- Flaky tests still causing issues
- Staging environment reliability
- Documentation gaps for new services
## Next Quarter Priorities
1. Eliminate top 10 flaky tests
2. Improve staging environment SLA
3. Documentation sprint for new servicesSources: