"Just Enough" Documentation
Published: 12-04-24
Creating documentation is a lot like flossing your teeth - it's a chore, but it can ward away problems down the line.
Documentation does more than help others understand the work you've done though - it reminds you why certain decisions were made throughout the project.
But most importantly, it allows you to decentralize yourself as the go-to person for that application.
The Forever SME
Eventually, it's time to move to a new project. The accumulated knowledge that made the feature a success is now a ball-and-chain that prevents you from severing ties from your previous work, which hinders your ability to focus on something new.
Most developers can do this once, maybe two or three times before the context switching brings them to their cognitive capacity. Time that would otherwise be used for onboarding and learning is spent answering questions about your previous work, or providing support when the application goes down.
There simply isn't enough time or space left for any new information. And thus, you become "The Forever SME."
The Antidote
The broad overview and key pieces of information must be documented, preferably within the repository.
This is for two reasons:
- To prevent "lost documentation" that exists somewhere on Sharepoint
- To encourage frequent and easy-to-apply updates to documentation to keep it alive
In short, thorough documentation doesn't help anyone if it can't be found. And if there are barriers to updating it, it's likely that the insights a developer has while coding or troubleshooting and issue will be lost in the churn of daily activities.
This isn't new information, of course, and it's impossible to foresee all the points of confusion that onboarding deveopers might run into when learning your application.
So what's to be done?