As a non writer I found that even without the details there's just one very important and very basic insight here:
You don't have to say everything exactly once.
Until being exposed to this idea I always tied myself in knots trying to write one stream of text that serves as THE DOCS. It's impossible to do this well (once you know, it seems very obvious haha). Just realising that you can write the same info in different ways for different readers is very helpful!
There is even a lot of potential for communicating more effectively here:
By giving 2-3 examples, that describe the same thing from slightly different aspects, you can to some extent overcome the ambiguities of language, by letting the reader figure out the common denominator between those examples, which will be a lot less ambiguous that only telling it from one example.
Let me give you two examples more [...] ;)
(Related, this is a technique used extensively by writers like king Solomon in the book of Proverbs in the Bible.)
Giving a few good examples also has the benefit of demonstrating the author's own understanding. If the author can't describe the matter in different ways, it shows don't have a feel for "it", and they're not grasping it rightly or even touching it at all. I've found that audiences can sense when a speaker is out-of-touch, and will politely ignore them.
Separately, I've heard that the Nicene Creed and its ancillaries had the repetitions hardcoded to forestall natural schism/emergent mutations in the generational belief system.
I have a friend who's a pastor. As a basic rule of a good sermon he always quoted the old addage: "Tell them what you’re going to tell them, tell them and tell them what you’ve told them".
There's more art to it, because there's also an off-putting way of doing that, which frequently shows up in presentations: you're greeted with a powerpoint slide with the topics in bullet points, which the presenter reads out loud, then come the slides with each of those points, also read out loud, and at the end there's a summary that almost copies the first slides, and which --for good measure-- is also read out loud. That makes me want to forget everything that's been told.
It's an incredibly common mistake, for the presenter to put up slide after slide that is just a script of what they want to say - then your brain has to choose between listening or reading, to the detriment of both.
I have more sympathy with intro and outro summaries, as long as the bullet points are short and delivered one at a time while the speaker expands upon each one.
Slides should be a visual aid, not a substitute for presentation.
The best presentation I ever saw was done by a colleague of Mikel Harry's at a Six Sigma conference in Frankfurt. The presenter had no ready made slides but he had an overhead projector, three transparencies, a handful of dry marker pens, and an eraser. As he spoke he sketched charts and diagrams to illustrate his points. If an audience member asked a question he was able to provide an answer in both words and with another sketch.
Reminds me of Presentation Zen or the 10/20/30 rule which states that “a presentation should have ten slides, last no more than twenty minutes, and contain no font smaller than thirty points.”
The anecdote doesn't strike me because your friend the pastor said it, but because it's a rule as old as times that every high-schooler was taught.
- The introduction should announce the thesis and its development
- walk your way towards your thesis
- The conclusion should summarize your thesis (and hint at openings towards new grounds)
But somehow, everyone seems to forget it and is in awe whenever someone recaps it.
And every high schooler, TedX speaker, and Malcom Gladwell impersonator gets this wrong: It only works if intro and conclusion present a different view on the information, otherwise it's simply boring the audience to death.
Then the challenge becomes recording where each thing is recorded so that when it needs to be updated, you update it everywhere and don't end up with conflicting documentation.
And by then you have several people on the team who have thought the wrong way is the right way for months, never mind your support team probably giving end users bad information.
True, even when you are writing a scientific publication with a hard page limits (~8 pages), it is advisable to reiterate the core messages multiple times as you add more context and details:
= abstract
1) in this paper we show that X holds by evaluating Y against Z
= intro
2) the problem of A is important because B, however the X aspect was overlooked; we show that evaluating Y highlights real world challenges, in contrast to Z, that...
3) to sum up, we found that Y is better at Z because X
= related work
Z approached the problem as..., which improved..., but as we show further, this is not sufficient to achieve...
.. and so on - you circle around the main message over and over again in each section.
You don't have to say everything exactly once.
Until being exposed to this idea I always tied myself in knots trying to write one stream of text that serves as THE DOCS. It's impossible to do this well (once you know, it seems very obvious haha). Just realising that you can write the same info in different ways for different readers is very helpful!