Documenting your work is an important step for all technical roles. And excellent documentation is what separates the extraordinary from the average.
Think about it, have you had the pleasure of inheriting a former co-worker’s code base or responsibilities, and their notes were incoherent, which led to blockers and further slow-down of your work? What were your feelings towards that co-worker who left you with their mess?
Maybe you haven’t experienced that hardship because their notes were well organized and thought out, which made you feel appreciative.
Outperformers also use documentation to create a paper trail of all their accomplishments. Perhaps you’re looking for a raise, a promotion, or a new career. Having tangible evidence looks favorable when negotiating why you should get the compensation or job you’re pursuing.
Your notes can lead to a better portfolio or can be turned into tutorials and courses.
Ambitious junior engineers, or anyone who wants to learn the mechanisms behind how products are developed and adopted, turn to documentation to get up to speed.
Documentation is critical. However, logging details about your code is tedious and daunting for those who dislike writing. The good news is that there are different styles of documentation. Hopefully, one of these versions will comfort you in detailing your work.
Style 1: Standard Text
Of course, I was going to start with the type of documentation that people are most familiar with. This form of communication is crucial and cannot be skipped.
Your written documentation can be a README, a blog post, comments within your code, or a Jupyter Notebook.
Some methods offer richer context. A blog post, Jupyter Notebook, or README allows you to insert text in different fonts, images, videos, or sounds. Records like these are great for a general audience.
Commenting code is suitable for clarifying what a class/function does or describing how a function/class does its tasks. This route is geared towards engineers who’ll need to reference your code. When using this documentation style, use a standardized approach like Docstrings or Scaladoc.
Style 2: Demoing
Demoing is fun 🤩… at least for those who love showing off their work, enjoy teaching new topics, or are eager to present a product/solution.
In short, a demo is where you walk someone (or a group) through a feature of your code. It can be done live–like at a conference, via zoom, or prerecorded and posted on the internet.
Demos are an excellent way to improve public speaking, verbal communication, and written communication. The nice thing about demoing is that it doesn’t have to be over the top.
Your median can be simple yet highly interactive, like a shareable Jupyter Notebook. Or it can be just you reviewing how a product/feature works.
Just remember to keep your audience in mind. Your presentation should be clear and to the point. Grab your audience’s attention as quickly as possible and retain it for the duration of your demo. Anticipate questions or allow room for discussion.
In the end, it should feel like you talked for at most 70% of the time, meaning you were the driver of the conversation, but you allowed for community engagement.
Style 3: Tutorials
Tutorials are similar to demos, but there’s an emphasis on knowledge transfer. Sure, in a demo, your audience will learn from you; however, they probably won’t recreate your work as a way for them to learn a new skill. That’s precisely what tutorials and walkthroughs are for.
Tutorials and walkthroughs are almost like alternatives to textbooks, but I think they work best as supplementary material. Textbooks can be dry and hard to follow.
Tutorials, on the other hand, are quick and straightforward to follow. You can think of tutorials as quick recipes, while a textbook is a large cookbook. Either way, tutorials are designed to be visually pleasing and as informative while trimming off the extra fluff. And by fluff, I mean theory.
Tutorials don’t usually go in-depth for theory. The information is meant to be applied right away. It helps the reader get up and running with new software or algorithm.
Tutorials can include videos, blog posts, Jupyter Notebooks, e-books, or git repo. Still, the goal is to teach a topic or skill to someone who lacks experience.
Style 4: Git Commit Logs
How detailed are your git commit logs? I’ll admit that I’ve pushed commits with very generic or not-so-descriptive messages, especially when I’m trying to work out a bug and nothing seems to be working. But having descriptive git commit messages is an incredible way to document your progress.
For example, when you’re ready to make a pull request (or during code review), your colleagues might look through your git commit messages to get a quick overview of how you solved a problem or created a new feature.
Now I’m not saying that all your commit messages need to be thought-provoking and insightful. Sometimes we repeat our messages several times, and that’s okay. However, I want you to remember that commit messages are a form of documentation, and people read through them.
Bonus Style: Tests
Yeah, even the test scripts that we write can serve as documentation.
Many tests are created to assert that a function performs a particular action correctly. A developer can refer to these tests to see how they can use your functions. Think of it like a tutorial.
Sometimes digging through an extensive reference library is intimidating, and engineers can get lazy. Looking through a couple of tests to see how the function was called can be more straightforward than reading through text-heavy documentation.
Some may appreciate that text-heavy documentation, but others want to figure out something quickly to get back to coding.
Conclusion
Documenting comes in various styles, but they all serve a similar goal. These resources improve knowledge retention and knowledge transfers, help you stand out, and enable better community engagement. Pick a style or few you’d enjoy writing up and practice that mode of communication.