Tag: documentation
-
Maxims of comments?
Several years ago Tom Scott made a video, The Hidden Rules of Conversation, which introduced me to the cooperative principle. They are the conventions that are generally followed by everyone in order to communicate effectively. I wonder if they can tell us anything about writing comments? Grice’s maxims Paul Grice was writing about the gap…
-
Mermaid diagrams
Famously an picture is worth a thousand words. That may or may not be true but a diagram can definitely help explain something. There’s plenty of software and online tools to help with this but, in my experience, making a diagram can still take a lot of time. It’s good to do but if you…
-
No comment code
My last post mentioned No Comment Code and my initial horror at the idea. I’d not come across it directly before last year. However I think I’ve seen it’s influence on some other developers. I’ve done a bit of research but will be using Don’t Write Comments and To Comment or Not to Comment as…
-
Markdown to PowerPoint
When you writing documentation for your project Markdown lets you concentrate on the words rather than complicated formatting. You can take the same approach with PowerPoint. There are multiple tools out there which will do this. I’ve used marp and it makes very easy to make a presentation quickly. If presentations are a big part…