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

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