Get to the point
Being able to build a story/narrative of your work is an important skill that’s rarely discussed in our industry. It’s however in my opinion a fundamental skill that you constantly use – at least that I constantly use.
Building a story is useful at all levels, starting with your pull request. You can send one massive pull request with thousands of files changed, but no one is going to properly review it. You should build a story around your change – and practically speaking break your work into different stages:
- Send a skeleton first detailing the high level plan for changes and upcoming PRs
- Implement logical pieces in small groups
- Connect pieces as they are ready until everything is connected
The same goes for writing docs, you can have a brilliant idea, but you need to build a story around it – I’m not talking about using extravagant words to make the project more appealing, but helping readers walk your train of thoughts. This means:
- Setting up the background/context
- Explaining the problem
- Proposing a solution and the rationale (or why it came to be and/or is the only viable path forward)
Last but not least, you should hone this skill because it will help you paint a fair picture of your work during perf. People will have a better opinion of your work if they better understand how you pieced thousands of projects/fixes together – and this is fair, you should get the appropriate credit for your work.
You still need a healthy technical foundation though – story building works only if you can build on good content.