I recently received a letter from my bank that was meant to explain something, but it didn’t. This reminded me of a fruitful conversation I had with someone on the Ministry of Testing slack community, about what motivations people might have for writing. In this post I’ll try to dig into that a bit, in … Continue reading What motivates your technical writing?
Category: Documentation
Just detail can lead to poor documentation
I've been around computers long enough to have encountered one problem many times. It's a problem that seems to be almost built-in to computers: poor documentation. In this article I'll focus on documentation of code that you use via its source code, e.g. an API, toolkit etc. There are mental tools you possibly already use … Continue reading Just detail can lead to poor documentation
Organising technical documents for a good user experience
I was doing some technical writing at work recently, and I realised that I had automatically and unconsciously used a particular structure for the document. It’s not something that geeks like me are always taught – I know it only because my Dad used to help people improve their technical writing. So, in case it’s … Continue reading Organising technical documents for a good user experience
Describing films and code using pictures
This article is the combination of a few different things. For a long time, I’ve wanted to visualise in some way the details of the plot to the film Ocean’s 11. Also, occasionally I get grumpy about decrees about how people should document their code. Finally, I recently attended a talk given by my friend … Continue reading Describing films and code using pictures
Blogging
A friend recently talked to me about blogging, and it got me navel gazing a bit. I’ve not really thought about how or why I blog, and I guess it’s a good thing to be a reflective practitioner. At the risk of being self-indulgent, this is an article about how and why I blog. As … Continue reading Blogging
Turn the information up to 11
Much of the job of communication is to pass on information to someone. When we design a user interface, it communicates on our behalf. When we write code, including test code, we communicate our purpose for the code to someone else (which could be a future version of ourselves). Sometimes we communicate more obviously and … Continue reading Turn the information up to 11
Documenting ASP.NET REST APIs with Swagger / Swashbuckle
Introduction Swagger is a way to document a REST API, and tools can automate much of this process (but not all of it). At the centre of things is a JSON file that describes the API. You can create this file by hand or use a tool to generate e.g. from the API source code. … Continue reading Documenting ASP.NET REST APIs with Swagger / Swashbuckle
Writing documentation can be in your own interests
Introduction Some people take the agile manifesto's ... We ... value ... working software over comprehensive documentation the wrong way. They think it means We don't value documentation This is: a) not the same as what the agile manifesto says; b) wrong, even if you act purely from self-interest. There are at least two selfish … Continue reading Writing documentation can be in your own interests
Balancing big picture and details when coding, testing and documenting
Introduction I very much hope that this avoids being a rant. I also hope it avoids being self-indulgently clever rather than being helpful. Finally, I understand that people learn in different ways; I think I like images and like to get the big picture before getting into detail. Other people like to be led along … Continue reading Balancing big picture and details when coding, testing and documenting
Trying to not get too ranty about documenting software architecture
This article is my thoughts on a video about documenting software architecture: https://www.youtube.com/watch?v=kv8XedJTEww A summary of the video is: Domains other than software architecture, e.g. maps or electrical circuits, do a good job of capturing useful and important information in a way that communicates this well – this is mostly in pictures. Software architecture does … Continue reading Trying to not get too ranty about documenting software architecture
