14 ms·

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 onc

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!

smeej 2y ago
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.
- 7bit 2y ago
  This. Repeating information is helpful. repeated information that became inaccurate isn't. It's a difficult line to balance
  - fmbb 2y ago
    Someone will trip on the mistake and report the bug and you fix it.
    - deleted 2y ago
      [deleted]
    - tjoff 2y ago
      You dont get a compile error if the documentation is wrong. Chances are you wont notice. And even if it eventually is fixed it is not obvious that the reason for the bug was that the documentation was wrong in one particular place.
      - smeej 2y ago
        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. It's messy.
elcritch 2y ago
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".
- tgv 2y ago
  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.
  - danparsonson 2y ago
    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.
    - ninalanyon 2y ago
      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.
      - HPsquared 2y ago
        The old ways are the best.
samuell 2y ago
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.)
- BlueTemplar 2y ago
  And two of them should be the most obvious example you can think of, and the weirdest example you can think of.
- hitekker 2y ago
  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.
deleted 2y ago
[deleted]
bbminner 2y ago
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.
ysofunny 2y ago
expanding this take perhaps too much ...even the source code itself "says", in its own way, the same thing as the documentation, just to a different "audience" (the compilers)

smeej 2y ago

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.

7bit 2y ago
This. Repeating information is helpful. repeated information that became inaccurate isn't. It's a difficult line to balance
- fmbb 2y ago
  Someone will trip on the mistake and report the bug and you fix it.
  - deleted 2y ago
    [deleted]
  - tjoff 2y ago
    You dont get a compile error if the documentation is wrong. Chances are you wont notice. And even if it eventually is fixed it is not obvious that the reason for the bug was that the documentation was wrong in one particular place.
    - smeej 2y ago
      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. It's messy.

elcritch 2y ago

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".

tgv 2y ago
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.
- danparsonson 2y ago
  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.
  - ninalanyon 2y ago
    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.
    - HPsquared 2y ago
      The old ways are the best.

samuell 2y ago

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.)

BlueTemplar 2y ago
And two of them should be the most obvious example you can think of, and the weirdest example you can think of.
hitekker 2y ago
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.

deleted 2y ago

[deleted]

bbminner 2y ago

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.

ysofunny 2y ago

expanding this take perhaps too much ...even the source code itself "says", in its own way, the same thing as the documentation, just to a different "audience" (the compilers)