It’s the process…

In a presentation for MarkupUK 2019 called Documenting XML structures, I introduced the term “knowledge bubble” (https://markupuk.org/2019/webhelp/index.html#ar12.html). What I meant is that when you’re busy doing something complicated, like programming, it’s very hard to imagine what people on the outside don’t know or will understand. You’re in the middle of it now and everything is therefore understood and crystal clear.

You have to acknowledge to yourself that you’re in a knowledge bubble during development. And being in a knowledge bubble means it’s impossible to write good documentation because you don’t really realize what the reader doesn’t know. This is not only true for documenting things (in separate documentation), but also for writing good code comments and judging code comprehensibility.

So how can we overcome this obstacle? Here’s how I try do this:

Key is that after you think you’re done programming, take a pause/break/weekend/vacation/cup of tea and always revise/review what you’ve written. And also: important commenting is best left to review time.