Sorry, let me emphasize that. Document EVERYTHING!
Crashes happen. From space rovers to the smallest C programs, things break. The severity may differ but there’s one common theme: they are a pain in the ass to debug.
So document everything. You can even document this page in the notes for your team so that they understand the importance of keeping track of your workflows.
Etsy taught us to measure anything, measure everything related to network, machine and application metrics, and we hope to inspire a slightly less than healthy obsession with documenting the steps taken for your network, machine and application processes. It has saved us numerous times and will definitely get you out of a bind when the pressure starts to mount and fixes need to be pushed immediately. Similar to how test-driven development increases confidence in refactoring for code, documentation increases the confidence in refactoring for things such as server configuration, database tweaks and data backups/imports. Having a baseline and record for your setup makes it easier for the next person to come in and start adding modifications, no matter their experience level. It also allows for a repeatable, step-by-step approach when issues arise.
What we document:
- Setup for new employees
- A visual view of our network infrastructure
- Database schemas
- API versioning checklists
- API error responses
- Debugging processes
- Deployment processes
- Planned roadmaps
- Relevant news that our team would be interested in
- Tasks and status updates
- Asana for tasks
- Hipchat for communication which is key especially when deploying or debugging
- Google Drive for a central location to keep your documentation
- Thoughtbot’s Laptop script for turning Linux or Mac OS X machines into development machines quickly
- Better Specs: Rspec guidelines with Ruby
Not everyone is a Unix or <insert obscure programming language here> ninja. However, we believe that given the right materials they can get up to speed extremely quickly. It’s not just about the team as it stands currently, but the team as it will become in the future. Documenting everything decreases time and frustration when working and makes the learning curve much faster.
Soundtrack: “B-Boy Document 99″ by The High & Mighty feat. Mos Def & Mad Skillz