Technical Writing ✍️
Last updated: Mar 08, 2023
One reason I started this site/blog was to sharpen my communication skills.
Since software engineering is my craft, most of what I write is about software.
And when it comes to tools aimed at engineers, including open source, software without good docs doesn’t go far.
Is communication about software is more important than the software itself? After almost two decades in this profession I started to ask myself this more and more.
I had some answers in a great talk by a more experienced engineer/lead. In How to wag a dog, Daniele Procida goes deep into how documentation drives software engineering. And proposes Diátaxis as a systematic framework for technical documentation authoring. Talk description:
Dogs wag their tails, and when the opposite happens, it represents distorted priorities and a disturbing, problematic reversal of the proper order. But not when it comes to software and its documentation! I believe that the tail of documentation can and should wag the dog of software, and I’ll show just how powerful this tail can be.
Since you’ve read so far, I hope we agree that technical writing is at least as important as writing code. This page goes through my technical writing efforts. Last updated: see above.
Open Source
Django project docs PRs:
Improved docs about cached database backend
PR title:
Prioritized cached database backend for cached sessions in docs
Improved guidance for making good use of signals
PR title:
Improved guidance for making good use of signals.
Work to have black applied to code samples in Django docs
This was a result of multiple PRs, several of which were closed. As they were exploratory in nature.
Most of my work has gone in this commit.
My commit builds on Carlton Gibson’s PR to apply rst (reStructuredText) code-block to non-Python code samples. In my commit I manually made all Python code samples pass when blacken-docs is run.
In this effort’s final PR, Mariusz Felisiak applies changes to have blacken-docs run and actually “blacken docs” whenever docs are changed.
That ensures any Python code is “blackened” going forward 🚀
Setup blacken-docs for DRF
Pull request here:
- Applies manual fixes for
blacken-docscommand to pass without errors. - Adds
blacken-docsstep to precommit hook, which runs in DRF’s CI process. - Adds changes made by command itself.
StackOverflow
I am helped by, and seek to help, others on StackOverflow. My StackOverflow profile.
Badge:
This website’s blog
Last but not least, this website’s blog section:
- Blog’s first page
- Blog posts archive, posts ordered by date published
Below is a handpicked list of code-heavy posts based on a combo of personal bias and page views: