Tag: documentation
-
Picking a name
I’ve talked about good names before but it only briefly touched on the importance of exactly which words you choose. Words have meanings and connotations. Pick the wrong word and people can get the wrong impression. However good your documentation is that won’t help if the developer thinks they already know how to use it.…
-
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…