142

I work in a field where you can get sudden requirements to communicate a lot of highly technical stuff from time to time. Sometimes this stuff is really involved. Like, you can chat with people about it, but you know that the next day you won't have covered all the angles, and half will have been forgotten.

The problem I am experiencing is that some key people will not read. These are highly capable, technical people, but they just will not or can not study technical analyses. They claim they have, but you can just see they have gleaned nothing from it.

What can I do to help them digest the information I need them to digest?

Sentinel
  • 2,473
  • 2
  • 12
  • 18

17 Answers17

225

It sounds as though the level of intricacy and detail of the documents you are writing are above my current pay grade, but as a former middle school teacher I have a few tips that may help. (I had to get kids to try and read too!)

  1. Try creating an outline or bullet point list that will highlight specific aspects of the document you are wanting them to read. By highlighting aspects, and even having open-ended questions in the bullet points, you are allowing people to reference main points of your document. If you use a question in the bullet point it helps to influence the reader to try and answer it for themselves.

  2. As silly as it sounds, bold and italics are a great way to attract the reader's attention and emphasize what you are trying to convey.

  3. Sharing documents and adding comments by shared users allows you to see who is paying attention and who is contributing. If the comments are turned on in Google Docs or other shared applications you are able to gather input from other people who are contributing.

  4. And last, there's always good ol' conversation. Ask the people who seem to be slacking if there is a reason they're not fully engaged. Express the importance of documentation, follow-ups, and the attention to detail. Hopefully they are mature enough to understand the importance as well.

gfos
  • 105
  • 4
MacItaly
  • 1,839
  • 2
  • 10
  • 22
  • Actually 2) and 3) really help and when I can 3) seems to work best. It's like peer pressure. Problem is I can't do it in some important cases because the stuff can be sensitive from a security standpoint and whacking it up on google docs would be almost suicide. – Sentinel Jan 29 '19 at 21:55
  • But this is exactly the kind of thing I am looking for. Something tells me this is to do with "education" more than anything else.... Know what I mean? Some people are technical geniuses but their brains don't work in some ways so I need another way in. – Sentinel Jan 29 '19 at 21:56
  • 24
    Overuse of bold and/or italics is a great way to make text very difficult to read - be careful with that one. – Bernhard Barker Jan 29 '19 at 22:03
  • 12
    I would add a (5) - if this is important enough content that everyone is expected to make time to understand it, book a meeting (class/workshop) and present the material, allowing everyone involved to ask questions and engage with it. The OP seems to have just "conversation" and "formal email" in the communication style, and could do with branching out if their job is communicating complex technical information. – Neil Slater Jan 30 '19 at 07:49
  • 5
    And I'd add pictures if you can: flow charts, pseudocode, equipment photos, stat tables, UI screenshots, relevant cartoons, even. Just something that helps people navigate the document and inspires them to at least read the paragraphs surrounding the figure. There's nothing more disheartening than more than 5 pages of solid text. – Pam Jan 30 '19 at 11:32
  • 1
    I'd also recommend considering which font you use-- even for people without dyslexia, dyslexia-friendly fonts can make a world of difference for how easy something is to read. There's a lot of material out there for making your content more readable, purely from a formatting standpoint, and it makes a world of difference. – Cooper Jan 30 '19 at 15:46
  • 1
    @L.S.Cooper Dyslexia friendly fonts? Is that a thing? Hey you may have put me onto a winner here. Can you link me to this? – Sentinel Jan 30 '19 at 22:27
  • 1
    What Neil Slater said, calling a meeting 'forces' attendees to devote time to the material. Otherwise, when sitting at their desks and having a choice to read a technically challenging document or clearing tasks off their plate, the document loses. – Arluin Jan 30 '19 at 22:45
  • 1
    This study (http://dyslexiahelp.umich.edu/sites/default/files/good_fonts_for_dyslexia_study.pdf) suggests that Helvetica, Courier, Arial, and Verdana are all good choices. Dyslexie is a font designed specifically for dyslexics, but I find it much harder to read, actually. And, of course, there's the infamous Comic Sans, which is supposedly pretty good for dyslexics. – Cooper Jan 30 '19 at 22:46
  • Excellent suggestions. Most readers will only need a few key details from a large document; giving them a means of finding those details quickly is the best way to ensure they refer to your documents. And, of course, different readers will need different details. – DoubleD Jan 30 '19 at 23:25
  • Moderation may be key, but the only comment here with +40 just so also happens to be the only one using bold. I've taken a sample of the OP's work at SE : They don't use formatting... +1 – Mazura Jan 31 '19 at 18:50
  • They should also work on how they add links. Like here, one is click bait (because it doesn't have a description like this in parenthesis) and the other is unnecessarily long (and I still have to click that one too unless I can read hyphenated gibberish). – Mazura Jan 31 '19 at 18:58
  • "specific aspects of the document you are wanting them to read" - unfortunately with things like technical specifications, there's no getting around the fact that you need to read and understand the whole thing. – industry7 Feb 01 '19 at 15:48
79

Perhaps part of it was your writing style.

I have read and answered many questions on this site, but yours was, in fact, difficult to read. I'm wondering if this has something to do with it.

Even Einstein said "Make things as simple as possible, but no simpler".

  • Get down to the level of detail that is necessary, but no more detail than that.
  • Break things down further into the smallest pieces to read. Make sure your fonts are large enough, the colors in any charts are clear and that the data is meaningful.
  • Break things down into bullet points if possible.
  • MAKE IMPORTANT DETAILS STAND OUT
  • Solicit feedback from your audience.

The problem may be in your presentation. Rule that out first before you ascribe any laziness to your coworkers.

If it is in fact your presentation, at least that is something you can address. Laziness, not so much.

Community
  • 1
Old_Lamplighter
  • 159,693
  • 108
  • 436
  • 585
77

I struggle with this problem all the time. I've even asked about it here, only to get the question closed, downvoted, etc. I suggest that you give up and let them fall on their face. Or if they are not a total loss, then meet with them in person.

People who won't or can't read, do so for a reason. That could be apathy, illiteracy, the epitomous "busy", or that they sign your paycheck and think that you should do your job without bothering them.

If other people aren't willing to or can't make the effort, all the tricks from the other answers won't help you. They're good tricks, and will apply to people who are able and willing to read and/or be collaborative. However, the people that you're having problems with will only find such tricks condescending, or be irritated simply because you presented them with written words.

Source: Experience.

Community
  • 1
YetAnotherRandomUser
  • 802
  • 7
  • 10
  • 1
    I am tempted to mark this right now as the correct answer. A lot of the comments above make the assumption nobody can read the docs, but the truth is that most find the docs easily digested , well written and highly useful. A small but important minority will not read them. I am not easily discouraged. I will find some way to engage these people . Until then, I will hold your answer open. – Sentinel Jan 30 '19 at 23:00
  • @EthanBolker It seemed close enough the first time that I rolled with it. My intent is to point out that people like to claim to be busy as an excuse, like to appear to be busy, might even like being busy, but that it's a false premise, with a side of snide air quotes. There's a word like that that starts with epy... that that was the first autosuggest and seemed relevant at first, though now I see your point. – YetAnotherRandomUser Jan 31 '19 at 02:05
  • @EthanBolker It seems that epitome-ous isn't a word, so I'm kind of stuck unless you can suggest one... – YetAnotherRandomUser Jan 31 '19 at 02:25
  • 11
    @Philipp I accepted this as the correct answer because on reflection it is the most accurate: if you are working on a system where the main product is a protocol specification then those who will not take the time to recognize this fact, and do the necessary reading and writing, are beyond help. There is no solution. These people need to be assigned to roles that involve testing implementations of the protocol, not designing the protocol. (where 'protocol' could be any kind of spec, eg: a blueprint, etc) – Sentinel Jan 31 '19 at 14:36
  • 2
    @Sentinel In your post you claim that "The problem I am experiencing is that a lot of people will not read". Now you say that it's only a small minority. Which is it? If you've tried all the other suggestions and they don't work, I agree that you should just accept it having tried your best. This answer though, and I might have perceived it wrong, seems to suggest that it's not worth the effort to try to change things hoping it will solve the problem. – actaram Jan 31 '19 at 15:43
  • 3
    @TheWanderingMind This answer says that if they aren't WILLING then the tips mentioned previously won't work.This implies that the tips are worth trying. I do think this answer CAN improve things. If the team falls on its face enough, either the team will dissolve or they'll find a way to improve. – zr00 Jan 31 '19 at 15:56
  • 1
    @Sentinel As a developer I design protocol specifications all the time, but reading large texts burns me out, I'm much more a hands-on guy. I need to play around with all the data and functionality to get a good grasp of what the spec will require. If I want to learn about something I need for my coming sprints I glance the docs, watch a video or two and then create a test project with test data and I start experimenting. I keep the docs open and look up any specific thing I'm using to make sure I'm not abusing it, but I can't learn anything within a reasonable time from just text. – Kevin Jan 31 '19 at 16:38
  • @Sentinel Perhaps your people are the same and reading some technical document is just not the best way for them to learn? Can you prepare a simple playground for them? Or is the scope too large for that? Can you break the matter down into smaller chunks? Can they be put in a study group to learn together? – Kevin Jan 31 '19 at 16:40
  • @Kevin sure. Play. program. Test. BUT. What I need is for you to update the spec based on your findings. The spec must be maintained to a level that you can translate it to something for implementation of formal proofs. Can you fully read all the details and make sure updates are precise? – Sentinel Jan 31 '19 at 21:36
  • 1
    @TheWanderingMind My mistake. 'a lot' is misleading. Updated question. – Sentinel Jan 31 '19 at 21:39
  • 3
    @Philipp Failure to read communications already provided is the fault of one party. – user207421 Feb 01 '19 at 01:42
  • 2
    @Philipp I think you and the people that upvoted your comment missed out on the implicit subtleties of my answer that zarose's later comment makes explicit. – YetAnotherRandomUser Feb 01 '19 at 01:42
  • @YetAnotherRandomUser I would go further and suggest that there is an unnecessary bias on this site against answers that rightly declare that under certain circumstances there is no option. Tricks like calling meetings and dumbing down technical design documents with crayon colouring or highlights can't suffice. – Sentinel Feb 01 '19 at 06:01
  • Are you referring to other answers here by "all the tricks above"? If that is the case, it does not work. This answer has now been accepted and got some votes so the order is different. Can you fix this (by editing your answer)? E.g. by referencing the specific answers (probably best) or using "all the tricks in some previous answers". – Peter Mortensen Feb 01 '19 at 08:37
  • 2
    I complete concur. Worked with the same frustration for a few years. Talked to the CEO about it several times, but that didn't help at all. I reached a point though where I realized that the 'I'm too busy' worked both ways. If they were too busy to read the paper, I was too busy to help them, and would do no more than refer them to the documentation. The CEO came to me due to complaints about this, several times, but I explained the situation, and he believed my actions were reasonable, though he would demand the occasional exception. – rasmus91 Feb 03 '19 at 14:51
44

Amazon has a fascinating technique to address a related problem... Don't expect people to pre-read your complex ideas, they simply can't give it the attention it deserves, they're too busy. Instead, write up an executive summary of what's being proposed/decided, call a meeting, have everyone sit there and read it together, then they can ask questions afterward.

"No PowerPoints are used inside of Amazon," Bezos proudly declares. "Somebody for the meeting has prepared a six-page...narratively structured memo. It has real sentences, and topic sentences, and verbs, and nouns--it's not just bullet points."

In his recent letter to shareholders, Bezos details the work that goes into these memos, which he says may take up to a week or more to write and refine:

"The great memos are written and rewritten, shared with colleagues who are asked to improve the work, set aside for a couple of days, and then edited again with a fresh mind. They simply can't be done in a day or two."

[...]

"We read those memos, silently, during the meeting," says Bezos. "It's like a study hall. Everybody sits around the table, and we read silently, for usually about half an hour, however long it takes us to read the document. And then we discuss it."

Community
  • 1
Alex Cruise
  • 527
  • 3
  • 4
  • 20
    TL;DR: Start with a summary. – Tibos Jan 30 '19 at 08:35
  • 4
    I highly doubt that a meeting is a helpful strategy to convey detailed, hard technical information, unless the meeting is very different from the norm. I have a hard time even staying awake in meetings. Not everybody is a Hans Rosling. And often one doesn't know which detail will be important until it's needed. My usual way to read technical information is to get an overview and re-read in depth relevant parts when needed. – Peter - Reinstate Monica Jan 30 '19 at 10:57
  • 3
    So... they are too busy to read the document beforehand but clearly not too busy to sit in the room with a bunch of other execs and quietly read the same document? What?!? Does not compute... – JeffC Jan 30 '19 at 17:45
  • This sounds like it would involve a change to the corporate culture that the OP could probably not effect. An interesting idea nonetheless! – Hutch Jan 30 '19 at 18:38
  • 4
    @PeterA.Schneider it sounds like it is simply required time to read the material, even if the discussion is not particularly technical or productive in the context, the required time (i.e. management sanctioned priority) is the real benefit and also keeps people accountable for their respective responsibilities with technical content or decisions, since everyone sees you there, reading it. – crasic Jan 30 '19 at 19:18
  • 4
    This approach makes a lot of sense to me, actually! All of the details will be fresh in everyone's heads immediately after they all read the document, so the conversation that follows will be especially productive. And it's easier to focus on reading when everyone around you is also doing so in a quiet room. – Kevin Jan 30 '19 at 20:32
  • 2
    @JeffC Sitting down in a room and then talking about it probably has a two-fold purpose: 1: tells people its actually important/a business priority and you can't just skim through it 2: by putting the discussion literally as close as possible to the reading of the material, people don't forget less and don't get distracted by whatever else they've got on their minds. – mbrig Jan 30 '19 at 21:33
  • 2
    @mbrig You schedule a meeting to discuss and expect people to read it (not skim) beforehand. That tells everyone it's important. People need to be adults and plan to read the doc before the meeting so they will be prepared and close enough to the meeting so they can remember, etc. Another way to handle this is to post the doc online and turn on comments. People can add comments before the meeting. That gives the doc writer a chance to update the doc or respond to comments before the meeting. Then you meet and discuss a near final doc. – JeffC Jan 30 '19 at 22:07
  • 2
    @JeffC and as anybody who's worked in a big corporation can tell you, the results from that strategy are pretty mixed. I'm hesitant to write off something that works on the success and scale of amazon without at least considering it. Though amazon using something does not, of course, guarantee that its actually good. – mbrig Jan 30 '19 at 23:19
  • 2
    @mbrig I can't rightly disagree that it works because they are Amazon after all and he says it works. It just seems counter-intuitive to me that it would work any differently than setting aside time before the meeting to review the doc. I worked at Microsoft for 10 yrs and I can say that some people came prepared and some didn't but we never tried this approach. It just feels weird to me because it seems to rely on the fact that people aren't professional and can't be trusted to prep properly. – JeffC Jan 30 '19 at 23:25
  • You only get to invite me to a meeting like that once. Then I write a rule in Outlook to delete you. – Sean Houlihane Jan 31 '19 at 15:15
  • 1
    "Don't expect people to pre-read your complex ideas" - OP is talking about people whose job is literally to read and understand this stuff. – industry7 Feb 01 '19 at 15:51
  • The TLDR for me on this is that you need an authoritarian culture where rules around communications are enforced. – Sentinel Feb 03 '19 at 11:43
  • Everyone makes excuses to not even try a technique which is used by one of the most successful and innovative companies of the world. "We're adults.", "A meeting is bad for details. I read them when I think I need them" [although you don't know what's needed], "I have a hard time staying awake in a meetings." I can see why those meetings are not productive... The answer is perfect, don't change it. – Chris Jan 08 '22 at 21:00
16

Don’t make them read. I’m not sure if this can be applied directly to your current situation. The thing that stands out to me is that you want people to be able to become experts on the problem on the first go at the issue or to keep re-reading until they understand. That’s novel, but as you’re experiencing, unlikely. There probably isn’t enough time to do that.

I think a good thing that you might be able to do is diagram or draw whatever these things are instead of trying to textually describe them and all the intricacies.

I work with a lot of website front end pieces and sometimes those pieces can have a lot of underlying business rules and corner cases. The times that the most defects are generated are when we have to build from a great big word vomit user story that lists a mountain of requirements meaning that even if you read, re-read, and even read again, you’re likely to miss something key.

One project, we had user stories that actually conflicted with the graphical design document. More often than not, what was actually implemented was implemented according to the design doc because that could be understood much more easily and at a glance. It had flow graphs, UI mockups, and expected functionality, but the source of truth was supposed to be the actual user story even though those were way more difficult to read.

So the first thing that I think would help is if you tried to get everyone to whiteboard these processes and graphically documented them instead of writing long, boring, volumes of text.

I started working with library called Rx that deals with plumbing data about in a functional, reactive way. I read documents until I was blue in the face about how the plumbing was supposed to work. However, what really made the whole thing click were the marble diagrams that explained what data was going where, when, and why. These diagrams are part of the core documentation and every operator/function in the library has a diagram that matches the textual explanation of the feature so that you can quickly understand the thing you are trying to get a grasp of even if you’re just skimming.

Take a cue from that and try to find a way to allow for birds eye views to give a good enough vantage point of what you’re working on but also entices reading the detailed description as well. You say that some of the things you’re trying to detail are things like mathematical proofs, I would think that there must be some way to describe these things “in action” or applied such that someone can get a ballpark understanding of the concept and use the long form text description as a way to fully understand what’s going on.

Maybe I just like books with pictures.

zero298
  • 715
  • 5
  • 9
  • 2
    Ha! I love Rx.NET :-) Marble diagrams are a brilliant invention. I think you are right. I need to invent something that is equally effective but applied to my context. Yet another possibility might be to do the equivalent of producing pseudo code requirements. – Sentinel Jan 30 '19 at 07:34
13

In addition to @MacItaly's great answer, I want to add an additional point:

Make your main point right up front. The first thing someone reads in a long document should be a summary of what the document is about. The first sentence of every section should drive home the point that section is trying to make. All the details that hold that idea together can follow after that.

It's tempting to write a narrative that builds and builds to fulfilling climax before coming to a final conclusion. That's how good stories are written, and really, even the most technical documents are just telling some kind of story (even if that story is as dry as the operational temperature limits of widget Beta-5A). But it's not a good way to convey information you want your readers to absorb because it buries the main point in a wall of text. Don't make your readers dig for the point you are trying to make or their eyes are going to glaze over before they get there (this is especially true in a dry technical document). State it right up front, then fill in the details that support that point.

Seth R
  • 11,976
  • 5
  • 28
  • 49
  • 1
    You mean, make all my writing like you wrote this answer? Main point up front followed by all the reasons for doing so? What a concept! – FreeMan Jan 30 '19 at 13:58
  • 2
    @FreeMan was that meant to be sarcastic? – WendyG Jan 30 '19 at 14:24
  • 3
    @WendyG slightly, but also to emphasize that the answer was written exactly the way he suggested doing so in his answer. I found it highly effective. (And am making note of it for personal use.) – FreeMan Jan 30 '19 at 14:28
  • 2
    I do try and practice what I preach. – Seth R Jan 30 '19 at 15:05
  • 3
    This is a very important point. I don't remember where I heard this, but as I understand it, learning works best when you have some "hook" to hang new information on. Having the big picture right up front gives people hooks to attach all the technical details to. – Cooper Jan 30 '19 at 15:52
  • 2
    @L.S.Cooper, people also have a tendency to skim. When they do, they usually only pay attention to the first sentence of any given subdivision (page, paragraph, chapter, etc.) and decide from there if they need to read the rest more closely. I like to write under the assumption that most people will only read the first sentence I write. Then I ask, if there is only one piece of information I want them to come away with, what is that going to be? – Seth R Jan 30 '19 at 16:17
  • Cute notion. Here is an example of a document that needs to be read. Someone will not read it. Where do I add the main point? https://tools.ietf.org/html/rfc793 – Sentinel Jan 30 '19 at 23:05
  • 2
    @Sentinel That document most definitely does not need te be read. Even if I forced myself to read that document (I wouldn't, even if my boss told me to) I would be no closer to remembering anything about TCP than if I just tried to write an app using TCP and seeing what kind of things go wrong. Both of which are somewhat bad ways of learning about TCP. Instead, if you could provide a possibly incomplete document like this I might actualy learn something about TCP that I can use when I need it. – Imus Jan 31 '19 at 13:31
  • @Sentinel, I'd say the author of that did a pretty good job by putting it in the preface and the first sentence of the introduction. – Seth R Jan 31 '19 at 15:15
  • 1
    @Imus Jesus it DOES need to be read if your job is to make the fecking document. Even through building TCP networks. As I keep saying, the end product is the spec, not the network. – Sentinel Jan 31 '19 at 21:28
  • 1
    @Sentinel so what you're saying is that you have a bunch of nerd's nerds writing a new spec for something as foundational as TCP and you can't get them to read the previous spec's so that they can make the new one? If that's the case, that premise in your question would seriously help make your point more clear. – YetAnotherRandomUser Feb 01 '19 at 01:48
  • Lno it's just an analogy . People keep making assumptions. I am trying to say in no uncertain terms that despite unnecessary protests from some comments, the docs must be read. @YetAnotherRandomUser – Sentinel Feb 01 '19 at 05:50
  • 1
    @Sentinel Yeah, I'm picking up on that, but when you drop an RFC as an example, that changes the context substantially. Out of the kiddie pool and into the Multiple Gold Olympian club, to use a swimming analogy. – YetAnotherRandomUser Feb 01 '19 at 14:26
9

As a technical writer and document manager, I write and go through a lot of highly technical documentation and expect users to read them. You can't make people read. But, there's two things I've learned to help people get through them with the important information.

  1. write for someone just off the street.
  2. pictures, lots and lots of pictures.

For item 1. as mentioned by others, bullet points, tables, bold, highlights, that kind of thing really helps to draw the eye to the important parts. Sometimes it makes the document longer but if someone that doesn't know details already can be drawn in and grasp the most important bits, it helps.

Item 2. I don't mean just pictures, but diagrams, flow charts, icons (like in the "for dummies" series) code snippets, whatever. Again it helps draw the eyes, but it also helps those who learn visually, not through reading.

Also alternate between these and the placement on the pages. These things also help people go back later to maybe look in-between them to find the important bits.

TLDR: don't just give a wall of text and expect people to find the details in it. Break it up so their eyes can catch what they need.

poeticvampire
  • 191
  • 1
  • 4
  • 1
    Based on the comments on the question involving @DonQuiKong and JohnWu, I would suggest keeping the END USERS in mind. It appears OP is concerned more with technical folks who are already familiar with the project. Even if it's purely internal, imagine if you're all Hit by a Bus and then brand new folks have to maintain it! – zr00 Jan 30 '19 at 21:28
  • Yeah think of this example. you have a team working on the control systems for automatic shutdown of a nuclear power plant when internal conditions become abnormal. As the team develop the system, they encounter new or unexpected requirements in how the system must be built. But every alteration must result in a corresponding change to the manual shutdown procedure documents for technical end users . Those building the automatic procedure s must validate the manual process es. – Sentinel Jan 30 '19 at 22:49
  • I understand, but my technical writing is usually for engineers. And in Sentinel's example, that's exactly where I would do something like this. Engineers are lazy (I know too many of them and was one initially) they're not going to read through a lot of text but even a brand new, highly trained engineer also may not know a particular company's procedures. And so yes, when I talk about someone "off the street" that's not always like child, yes, you do need to expect some level of foreknowledge. – poeticvampire Feb 01 '19 at 17:29
  • @zarose And as for being hit by a bus, my current company had just that situation, now I'm writing a lot of documentation to fill the gap of what they considered a "genius" for low level engineers. – poeticvampire Feb 01 '19 at 17:30
5

I struggle with this in my current job as well. It's difficult to get an answer out of seemingly nearly everyone in the company via email. This is compounded by having a satellite office hundreds of miles distant. We hold Skype meetings with them, but it doesn't seem to help much. I've resorted to sneaker diplomacy, get up from my desk & go talk to the person that I need information from in person. Of course trying to do that over Skype is iffy at best.

One of the better things I learned in the US Navy with regard to communication was:

Tell them what you're going to tell them. IE: Executive summary or TLDR

Tell them what you wanted to tell them.

Tell them what you told them.

Even with this approach, we still run into issues with people who never read the email detailing changes we've made to their software and why and we get questions. However the flip side of that is also true, my company has a stellar record of finding workarounds when something doesn't do what it's supposed to and don't bother to file bugs about the original problem because they've found the workaround. So we won't even know when something is broken.

EG: One time one of our automated calibration machines stopped running calibrations. Our techs switched over to running the calibrations by hand (much-much-much more time intensive, and human error prone) and never told anyone about the machine not working properly. A year goes by, lots of overtime is happening because they can't keep up with the work load. My colleague (who used to be a calibration tech) happens to be in the calibration lab one day and notices that nobody is using the automated calibration software and asks why. The techs explained that it'd been broken for "a long time" and they just did it manually instead. Five minutes of investigation showed that the hard drive was full, packed solid, so every time the software was started, it tried to write a file, couldn't, errored out (saying that it couldn't write the file) and quit. This is by design, if you can't write to the files you can't process a calibration. He deleted about ten years of log files from the machine freeing up several gigabytes of data, and voila, the automated cal machine started working again.

delliottg
  • 890
  • 6
  • 11
  • 4
    Lol. I wonder if political correctness isn't the fundamental problem. Back in the day if a team spent a year working overtime because someone ignored a memo, that someone would lose their f***ING front teeth and maybe a collar bone. – Sentinel Jan 30 '19 at 23:23
  • 1
    The problem is that this particular calibration job is entry level and turnover is high. It's rare for someone to last six months, so tribal knowledge is constantly lost. Either they move on to another job, or get promoted and another tech has to be trained. We've also learned that people simply won't read or act upon error messages, so for our newer software, we have automatic bug filing software we wrote, so even if they ignore errors, we'll still know about it. But not all of our software has this ability, some of it was written a LONG time ago. – delliottg Jan 31 '19 at 17:12
  • Oy. Repetition is not necessarily a good thing, as while you think it leads to comprehension, usually it only leads to boredom. This advice of telling them what you're going to tell them up front has led in my experience to droning on and on, twice. Yes, do make it clear what you're going to be talking about, but in a sentence. A paragraph at most if it's extremely complex –  Jan 31 '19 at 18:05
  • I agree with your sentiment. The summary should be just that, short & sweet, and the summing up shouldn't be any longer. I'm in favor of fewer meetings (they largely just waste my time) and if I have to go, short ones that are to the point and don't wander off topic. – delliottg Jan 31 '19 at 22:10
  • Re "our automated calibration machine": Purchased or one your company makes the software for? – Peter Mortensen Feb 01 '19 at 09:01
  • One we write the software for. In this case written about 15-20 years ago in VB by a non developer. It's loads of fun to maintain. – delliottg Feb 01 '19 at 13:54
  • Based on that experience, did you add a check for free hard disk space (either in the application or by some IT means) or at least a better error message, pointing to the exact reason (or at least mentioning the possibility in the error message - this would only require changing fixed text)? (Updating the application in the field may or may not be non-trivial.) – Peter Mortensen Feb 02 '19 at 11:21
3

I work in a field where similar situations arise. Unlike many answers and probably on the lines of OP's question, it's important to notice that it' not always about your writing. There are technical documents and commercial proposals from third parties that people need to read.

The problem is, if you are the only one reading a document, then nobody values the effort you put in.

The mitigation are case-by-case and depend a lot on your level of authority within the company. If you are a new employee, I'd suggest calling meetings to discuss documents where your highlights are shown in a presentation. You get your point across, but people may still not read the thing. If something you wrote requires attention, don't expect everyone to read in detail (specially if it's something you haven't yourself proofread once), ask a trust worthy colleague now and then, maybe reach to your manager saying something on the lines of "this report needs a reviewer, but I know it's pain to do so, therefore I don't feel comfortable asking a colleague as if it was his favor to me...". If the reading work is actually necessary the manager should assign someone with the reading task and take note if the person does a proper job.

Note however, that maybe all this reading may not be as important as you think, and possibly not everyone has to do it for all reference materials.

If you are a manager, there are other ways to cultivate discipline in the team, but from the question text, this seems not to be the case.

Mefitico
  • 3,632
  • 2
  • 14
  • 38
  • Bang on. The team has no management. It is entirely self organised and members are paid without assessment. Entry to the team depends on having identified weaknesses in the thing being produced or on having taken it forward on new opportunities, while external. – Sentinel Jan 30 '19 at 07:27
3

Application and Iteration

Already a lot of good answers have been given. I'd like to focus on the information handling process instead of the information presentation.

People need time to digest complex information. Even with a very good presentation not all information will stick. A good way to learn is by application. To get it all to stick a process of multiple iterations of reading and application can be used.

An example of a process

  1. Read to get the main ideas.
  2. Try to apply the ideas
  3. Get stuck.
  4. Re-read to get the details. New experience will help to understand
  5. Try again to apply

Repeat steps 3-5 till the information is processed.

jos
  • 138
  • 4
3

First of all, if the amount of technical material is large, it's not going to be possible for most people to take it in quickly. I remember back in grad school it typically took me 2-3 hours per page to read and really understand highly technical material.

That said, there are two general classes of documentation --

  1. Documentation that someone just wrote. Such documentation will contain unclear writing and even outright errors. The best way to understand what is intended is typically to write unit tests and to ask questions when something is unclear. I'd encourage them to do that. Then if you give an answer, they can be expected to show their understanding of that answer with a unit test.

  2. Documentation that has been around a long time. In that case, a community will exist. You may be able to encourage them to take their questions to that community.

Lastly, if you are able to read and grasp such things quickly, remember that you have an unusual talent, and not everyone can do that.

William Jockusch
  • 295
  • 1
  • 3
  • Yes it's a bit of both, and yes we expect people to spend literally weeks understanding, testing, implementing and contributing to these blueprints. But the issue is some people prefer to experiment in implementation s. – Sentinel Feb 01 '19 at 05:54
2

Mathematical proofs are hard to discuss verbally, though I'm sure I'm not fully imagining your situation.

My suggestions:

  • Request written responses in the form of annotations to the original document

Giving people time to read the documents, and then write down their thoughts, can help you get more formal, attentive reading sessions from these people. The annotation style makes sure that they are connecting their responses to actual portions of the original document (less scope for misunderstandings, and those that are present will be easier to find).

You mentioned in comments that the people you are describing might prefer not to respond in this way, but it also seems like their preferences are not tenable for you. If you have to make them engage more, this might be a way to make it happen.

  • Write collaboratively

People can blow off reading something. That's harder to do if you're writing that thing. If these people are responsible for certain sections, or if you have meetings where everyone goes over sections together, you can probably get them to engage more with the documents. It's sort of like supervision, but very light.

  • Ultimately, you can't force intellectual effort

This is more of an aside, but you can't make people think, and there is generally a limit to how much you can condense precise information. If they are not driven enough to do this on their own, then adding some sort of incentive for them to do it might be the only way to get them to volunteer the effort. Some mechanism for rewarding the effort (or punishing failure to make the effort) might be necessary.

Upper_Case
  • 6,014
  • 1
  • 22
  • 27
2

Slap an Executive Summary on it

I worked in a region of the world where reading was not tradition, and nobody would read before endorsing/adopting my documents/programs.

So I put a powerpoint (simple bulletpoints with pictures) of the summary, bound it, made it look pretty and attached it to the top of the full document. Staff reviewed it for accuracy and completeness, decision-makers read the 10-slide pictograph.

Mikey
  • 1,116
  • 7
  • 12
  • Reading was not tradition? Meaning most of the population was not literate? – YetAnotherRandomUser Feb 01 '19 at 01:50
  • Re "region of the world where reading was not tradition": Based on actual experience, that would fit Toronto, Canada. – Peter Mortensen Feb 01 '19 at 08:54
  • @YetAnotherRandomUser - very well educated; literate; but in the Gulf there is a tradition of simplification (Urban Planning is my field) and quick decision-making requiring us to provide highly visual and oral presentations with a level of trust that we are experts in our field and our recommendation is valid. – Mikey Feb 01 '19 at 11:57
2

Mefitico's answer contains some excellent points, but I also wanted to posit that the incentives for reading the documents may not be appropriately weighed. You mentioned that there isn't a manager in this situation, but presumably there's some evaluation of performance -- if a "deep reading" of the materials doesn't provide enough benefit relative to charging ahead anyways, people will optimize by avoiding it. This suggests that the deep reading isn't actually required to do the job effectively, or at least it's not measured as such.

As an engineer, one thing that helps me at work is if there's a way to tie-in the tangible goals with the required understanding of the materials; that's one way to ensure that relevant parts of the document are read. For example if the goal is "run Algorithm XYZ on data sets A, B, and C" and you have a write-up about Algorithm XYZ, that's probably the fastest path to finishing that goal. But if you asked me to read the same document on Algorithm XYZ without actually allocating time to read it or a goal to tie it with, it will be very low on the priority list.

user98871
  • 21
  • 1
1

Simple, just remind them where to read the information every time they have a problem with it or every time they don't know it. Eventually, through the power of repetition, people will start to just associate reading with learning.

Other than that you need to make sure your documentation is well written, otherwise no amount of RTFM(Read The Full Manual) is going to make someone read it; people will not read things that make their eyes bleed.

1

The fault lies in the reader or in the writing, or both. Since your question doesn't really suggest what the problem is, it is hard to suggest a solution. You say the readers are competent, but leave open whether they are refusing to read or are unable to read the material. If the former, the question is why? (Time constraints? Lazy? Other things are more pleasurable?) If the latter, that suggests they are not competent.

What you can try to do depends on how much you can influence the author(s) and/or the reader(s). If the issue is strictly a communication issue, an excellent book is "How to Read a Book", by Mortimer J. Adler. Use the information in there to encourage the authors to make life easier for their readers by writing well, and to encourage the readers with tips on how to do a better job of getting the most value out of whatever it is they are reading. There are general principles that apply even to works that are not books. I can't recommend this book highly enough.

Another guide to writing well is Strunk and White's "The Elements of Style".

Kevin
  • 11
  • 1
0

Some perspective from the other side of the fence:

In a previous job I had a lot of documents I "needed" to read. Typically requirements captures design documents etc. I often didn't read them past skimming.

Why? Well often "needed" in this context was: "helped the author".

For example, they wanted their design to be used as it got them credit and reinforced the "I solve the hard problems, they just implemented it" view of the process. If this is the case: great. But then you don't have a problem. I read the document because I have too. In practice, often the document was either:

  • Fluff that really just restated something that the author was given (that I had access too).

  • Not complete enough to use.

  • Was sensible and reasonable, but:

    • Didn't apply to the way I was going to interact with the project.

    • The situation had already been deviated from and difficult to "get back on track".

  • Sometimes: Wrong, contradictory or silly.

After I while started ignoring vast swathes of stuff I probably should have been reading and making my own way as, on average, this seemed to work better for me.

It's worth noting a few things:

  • That doesn't necessarily need to be the way it is, just the way its seen.

  • It doesn't necessarily need to be anything you did. Once the mindset of: "this is just one more thing I need to pay lip-service to before I can get on with fixing things", you will be fighting an uphill struggle. Not only because they won't read it to find out, but it will colour how they read it when they do. For example, you stress they need to read the documents. With an open mind, this could easily be read: "There will be significant downsides in not doing so for the business/project, that I haven't included because they aren't relevant/necessary." However, my first thought was the sceptical one I am warning you about. I can't know, but once you start seeing the patterns...

  • While the time spent reading was a factor, it was only a very small one. It's frustrating to be told: "do it this way, with that result" when the two are mutually exclusive, no matter how succinctly you put it.

So, what can you do:

Ask nicely and it explain why it benefits everyone/them. This never hurts, and if its a question of motivation, especially if the problem is they perceive themselves as outside the loop this, can go a long way.

Get, feedback if you can, as to what it is that's causing resistance. It may well be something that's impossible to fix like they just don't care about any of it, but I would think that's unlikely (if they really didn't care, they wouldn't come off as technical and competent, that requires at least a bit of commitment). I think it's far more likely that it's something you can fix. I clearly can't speak for everyone but: I can't see myself being reluctant to share my objections, and figure out how to progress, in a forum that I thought was about fixing the issues, not assigning blame.

drjpizzle
  • 101
  • 1