Untangled Development

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 more important than the software itself? After almost two decades in this trade I started to ask 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-docs command to pass without errors.
  • Adds blacken-docs step to precommit hook, which runs in DRF’s CI process.
  • Adds changes made by command itself.


I am helped by, and seek to help, others on StackOverflow. My StackOverflow profile.


profile for Joseph Victor Zammit on Stack Exchange, a network of free, community-driven Q&A sites

This website’s blog

Last but not least, this website’s blog section:

Below is a handpicked list of code-heavy posts based on a combo of personal bias and page views: