Document for Life.

Documentation, the dreaded word developers (and everyone else, really) hate to hear.

That pain-in-the-behind activity the management looks at as a needed hit on the budget, that low-priority, mundane, un-exciting grunt work that project and product manager are repeatedly reminding their teams to keep on top of! UNTIL a critical piece of information is needed, or some sense is to be made from the mountains of financial and other data in the organization. Only then Documentation is seen as a valuable must-have, should-have-done effort.

Most often it’s an after-the-fact situation. So the organization starts a “new” project to document better and push the hype when the fire is hot, until its not! again. The endless loop continues…

“Hey, you’re not telling me anything I don’t already know” you say. You’re rolling your eyes and your mind is already moving on to the next urgent tasks on your to-do list. I don’t blame you, they need attention.

But if you are in any leadership position in your organization and don’t have a proper documentation system in place or are not actively investigating and planning for it you’re going run into the quicksand.

If you have a system that’s awesome, congrats. Just check your system and process against these points and see how it fares.

1. Documentation is not only for the developers, it has to go thru the entire organization — don’t ask your teams to do what you yourself are not willing to do!

2. The systems should be easy and integrated. If you add more work it’s just going to be that much more difficult — at min if you add additional activities in one app take something out of other systems they have to work in so it becomes balanced.

3. The process has to start from interviewing and hiring. Into onboarding and internal training systems — set the expectations from the interview and give priority to documentation in the selection process so you pick team members that get it.

4. Provide incentives, everyone loves (and deserves) being recognized and rewarded.

5. Allow time in the process for the time it takes to document, don’t just assume anyone will magically get the project completed and documented in the time it takes to only do the coding and unit testing. Be reasonable.

5. Genuinely appreciate investing on documentation excellence — the ROI is hugely positive if you plan well and use the right tools.

6. Remember and demonstrate every day that a project is not well documented it is NOT complete, even if the code is complete and people are using it! Convey this to your vendors and do not make full payment untill the documentation is delivered and approved as usable!

- Don’t take it too far: determine what level of documentation is beneficial and plan to get that into the daily workstream of people. Un-necessary details can break the camel’s back.

- Chat software, email, sms, slack, etc. are NOT good documentation tools. They are awesome for their specific roles but finding meaningful, useful and “complete” information is extremely difficult, time consuming and often just not possible with these tools.

- Get educated and learn the best practices of creating well-documented projects, and the systems needed to inject this into your organization.

- Don’t wait till you’re an enterprise to address documentation. If you’re just starting out or a single-person team start with yourself — team of 1. Don’t wait for others to do it for you. I promise you others will wonder how you’re so organized and can find important information so quickly after a while. Build on the system as you get more team members added.

- Get feedback from the line when designing a system, don’t come up with something you think is good and force it on people — it will NOT WORK!

Interested to hear what systems or processes others use for documentation, and words of wisdom and lessons from the trenches?