Developing Process Documentation

Sharing knowledge is something that I feel strongly about so much so that I made this project. It's commonly overlooked because we often forget what it's like to struggle through something once we've completed it, saying how silly we are for not getting it sooner. I feel like this theme is especially common among developers. But when you're working in a team its important to share the knowledge you've gained through solving problems so that your whole team can benefit. Otherwise the rest of your team will solve the same problems over and over again with varying results.

The more we share knowledge, the more we communicate with each other, the more we understand each other, the easier it is to identify and solve team problems.

Process documentation is one of the most efficient ways to share knowledge, let's demonstrate.

Without documentation:

1. Teacher shows learner how to do something

2. Learner learns what they can

3. Learner #2 wants to know the same thing

4. Teacher is busy, because they know stuff, so Learner #1 teaches Learner #2 what they remember

5. Learner #2 learns what they can

6. This continues in a chain of chinese whispers and forgotten details

With documentation:

1. Teacher shows learner how to do something

2. Learner does it again while documenting the process

3. Learner asks teacher to review their documentation. Pull requests are perfect for this

4. Teacher notices a discrepancy and explains further

5. Learner updates documentation and learns

6. Documentation approved

7. Learner #2 wants to know the same thing

8. Finds document either because they were aware or someone informs them

9. Learner #2 is confused about something in the document

10. Someone explains further

11. Learner #2 updates the document

12. Learner #3 benefits from Learner #2's contribution

The alternative path is Teacher writes a brief document then the process continues at step 3 with the teacher asking for review.

Documentation is code for humans; its always accessible, easy to review and easy to improve. Being easily accessible means less dependency on people which means it takes less resources to do a task and less variation in results. And when there are issues, documentation can be reviewed and updated to address them. So instead of the process getting worse over time because people naturally forget things, it actually gets better. Imagine if production code improved itself every time it ran!

New people actually have more to contribute because they are more aware of all the tiny details it takes to make something work whereas experienced people are often unconciously doing things.

Documenting processes creates a better culture where everyone can focus on improving process and helping the team instead of playing blame games for poor results.

Checkout our development process.