People often say that one of the reasons Stripe is so successful is that their documentation is world-class.
Most companies, open source projects, and individual developers find this to be a Herculean challenge. I'd love to know if Stripe has any secrets to keeping their Docs updated. Though, my gut says that they likely just put in the work. Their Docs are incredibly important to their success.
Thanks to Stripe and a few others, developers' expectations have changed. Now they expect thorough, navigable documentation presented in a clean, error-free UI. If you deliver anything less, few developers will even bother with your API.
It really is amazing how much of a difference clear, up-to-date documentation makes to set one product apart from its competitors.
But I like to think about the impact documentation has on one's career as a software engineer. I've written extensively on this blog about the importance of written communication in the context of remote work.
There's so much value one can contribute as a software engineer that goes beyond writing code.
Some examples:
- You're working on a ticket where the acceptance criteria are ambiguous in some way. You ask the product owner for guidance on the parts that aren't clear. Instead of just moving on with your work on the ticket, go back to the ticket and either update the acceptance criteria to what you discussed with the product owner, or leave a comment on that ticket that documents what you discussed and how it affects the requirements.
- You ran into some error when running the system that you've never seen before. You ask in the team chat for help. A teammate has seen this error before and pings you with the steps on how to get past the error. Before continuing on with your work, write a bug ticket in the team's backlog with as much info as you can while the problem and solution are still fresh in your mind, and post a link to the bug ticket in your team chat.
- You discover while following a process documented in the team's wiki that some of the steps are out-of-date or not relevant anymore. Take some notes on what you found lacking in the wiki page, and then come back and edit the page yourself to make it clearer.
Most engineers don't do these things, and as such, they're great ways to stand out for engineers that make a point to do them. The work of an engineer involves so much learning—valuable information that is often lost when the feature is added or the bug is fixed, and we move on without documenting what we learned along the way, artifacts that won't be captured in the code alone.
Just as products can stand out with great documentation, so can engineers.
