Ben Brown gets the new developers up to speed:
Solution Summary cards are the name I have given to simple 1-page documents we provide to developers to get up-to-speed on a particular solution.
The primary use-case for these cards is to provide better on-boarding for new team members.
An additional benefit is that crafting these short summaries forces people to review how your teams are working and you will often start seeing areas which would benefit from standardization or simplification.
Click through for an example. I like this idea a lot for a few reasons, which I’ll enumerate here because I’m feeling it:
- Developers often won’t read really long documents. They might scan through the documents, Ctrl+F a few words, and refer back to it on occasion but rarely will they read through a document in its entirety.
- Long documents get out of date too quickly, as developers are typically bad at keeping documentation up to date, especially as deadlines loom.
- An artificial constraint like “Your summary must fit on one printed page” (either front-only or front-and-back) helps focus the mind. It makes you think about what the most important things to include are.
- If you are a consultant or just work on a lot of different projects, it can be painful trying to remember the details. Which jump box do you need to go to? Which were the most important bits of code? How do you run the unit tests and deploy the app locally? Even if nobody else ever sees the card, it can help you in the future.