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
Category: Documentation
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
