31

Most of what I write is non-fiction -- technical books, blog posts on open source topics, political stuff, etc. Lately, I find that some of the topics I am trying to present are much more technical than the intended audience is used to. I already plan to:

  • Explain terms the first time they are used.

  • Provide helpful asides (sidebars or footnotes, as appropriate) with explanations of concepts the reader might not already have.

    and

  • Use analogies to experiences already familiar to my readers whenever possible.

What else can I do to help a decidedly non-tech audience better understand a technical topic?

10 Answers 10

22

A non-technical test reader would be a helpful resource. Because of your knowledge you are blind for so many details, which you take for granted and couldn't believe that other do not know them. Listen to a test reader, what he does not understand, is the way to identify these blind spots.

The problem with this approach: you need regularly new test readers, because the old ones know too much.

Explaining terms at first use is a good thing. But don't forget a glossary where each term can be looked up. People tend to forget things, especially when they pause reading your book for one or two days.

Oh, and you need an index. There are too many technical books out there without an index. Unbelievable.

3
  • Unbelievable - Well, they are a lot of work to do well, and sloppiness is very easily spotted with them. Dec 20, 2010 at 13:58
  • 5
    @Charles: No, they are not a lot of work to do well. If you use the right tools (like Tex/Latex), they are much easier than you think. And if you care about what you have written, an index is a must-have. Dec 20, 2010 at 15:17
  • 2
    While I've used an index many times (and find it lacking in too many books), I've literally /never/ had a look at the glossary and often discovered it existed upon finishing the book. I don't believe in glossaries. If I want to look someting up, a (good) index will be most useful because it also leads me to the place where I initially learned about the term (with all the useful things surrounding it: pictures, related text, ...) Feb 4, 2011 at 14:42
12

Emphasize effects over causes

By this I mean don't lead your readers through the tall weeds, pointing out every individual weed. Walk them around the edge, showing them the size and shape of the field.

Your non technical reader cares about and understands things like "the server crashed and the website was down for six seconds, resulting in a ten million dollar loss and several lawsuits." They don't want to hear the details of the off-by-one error that caused the crash.

You know who's great at this is Neal Stephenson. If you want a good example to follow of someone who makes technical arcana interesting to liberal arts majors, Neal's your man. In the Beginning Was the Command Line is particularly good in this regard.

That thing you said about defining terms when they're first used

If you do nothing else besides this to help your readers, you're 90 percent there. I have read so many technical books that are incomprehensible because the writer couldn't be arsed to explain what a jank flinky is before going on for three pages about it. I think they just don't realize. So it's a great idea to get a non-technical reader to go through your MS and highlight any baffling terms that inadvertently slipped through unexplained.

2
  • 1
    I disagree about the key importance about making definitions of terms come at first occurence. It's good to watch for, but I've seen an opposite tactic used effectively, where there is fear that the term's definition won't be understood without being armed by explanation that needs the term. Giving a rough, working impression of a term before introducing the full definition can be effective. Dec 20, 2010 at 13:56
  • While Stephenson can be good... one can also use him for the opposite example. Cryptonomicon anyone? (including Perl code for Pointifex)
    – DVK
    Jan 15, 2014 at 22:00
6

Your short list is pretty good - especially the last point. I wrote a technical book, but wanted my mother to be able to read it (she has). I used analogies - mostly cooking to relate to software engineering terms, and they were helpful. Our editor wasn't a technical person either, and I think that helped too.

I also made sure the book had a lot of side notes with practical applications of the concepts. The goal was to take some complex information and make it accessible to a wide range of experiences, and the feedback has been positive in this regard. I imagine a similar approach would be successful in other technical areas.

4

A major pitfall to the "define on first use" model is that users will flip through a book (or its e-equivalent) to find the information they're looking for to complete the current task, then leave. If it's electronic, hyperlink the term to the glossary.

Never, ever assume people will be reading your book from the beginning to the end. Eschew "how to use this manual" chapters especially; they're insulting, if nothing else. Many people start with the index because it's (perceived as) quicker than slogging through the TOC.

Assume for an electronic document that people will be using a text search to find what they want, and accommodate them with a bit of helpful SEO (not just for spammers any more).

Make your subject headings describe the task, so they're easier to find in the table of contents or index (or by searching a PDF or a web page). Build a good index -- the lazy (but good enough) way is to auto-tag all your carefully-precise subject headings and "see also" pagerefs. Some doc tools will do this for you, AuthorIt for example.

Nobody reads this stuff for entertainment (at least we hope not). Nevertheless, everyone on the planet has a trophy wall of awful instruction manuals.

3

Maybe I'm missing something, or it's just so obvious no-one has bothered to mention it, but don't forget to tell them WHY (or maybe that's what @Ethan means by 'showing them round the field?).

That way, even if they don't follow the detail (or they skip it), they can still understand where you're trying to take them.

2

Pay attention to graphic design, i.e., non-textual, spatial organisation of material. Putting your helpful asides in boxes is effective.

Other matters of layout:

  1. Ensure there is plenty of space around text elements that organise material, such as subsection headings, quotes, &c. Lowering the density of information helps readers avoid feeling overwhelmed;
  2. Set off key ideas in the text. Distinguishing the text in this way accents the importance, and makes it easier for readers to come back to the point;
  3. Use diagrams to present the relationship between concepts.

Analogies are good, if your reader will be able to relate to them. If your readers will have difficulty, explaining an example will help: without them, readers are likely to have parsed your explanation without having formed a mental picture of what is going on. A running theme to relate to your examples together can make them more digestible.

Many mathematicians are good at expositional writing. Take a look at the answers to the Free, high quality mathematical writing online? question at Math Overflow. Children's textbooks are sometimes good as well.

2

You can also make it entertaining. Use humor. Keep your reader interested. Present things in unorthodox ways.

Use storytelling. Introduce characters, scenarios, and conflict.

Challenge your reader with questions. Make the content interactive.

Consider your point of view. You can use first person and relate your own experiences with the topics you are covering.

Check out the Head First series by O'Reilly to see some groundbreaking ideas.

1

Use plenty of examples. It's way easier to remember how a function works or the proper usage of a command if it's presented as an example. Show the example input and a sample result to complete the illustration.

And make the examples readily available online or on a CD so that readers don't have to recreate them.

1

Remember that grammatical nuances of a particular discipline can sometimes confuse readers more than the technical terms (which should already have been well explained)

Over on the English exchange, there was a question only today about "Significant fraction of reactor core inventory" This is a case of seemingly innocuous technical speak befuddling the casual reader. In said case it would be better to have written something like "A large portion of the materials contained within the reactor core" This way a reader can still be on shaky ground as to what a reactor core may be made up of but does not have to struggle with the grammar to understand the entire meaning of the sentence.

To add two cents about an index, they are great for referring to, to quickly remember what acronyms and the like are for, instead of having to trawl back through earlier text to find one particular item.

A great example of a work along these lines is Simon Singh's Fermat's Last Theorem, that enables the reader to see the maths as more of a journey from one point to another, in correct but casual language, rather than a dry text book on the involved procedures.

0

The most important thing in my opinion is showing them simplified yet informative graphics.

In any topic and for information where you can provide graphics do it.

For software projects UML diagrams has become the standard in planning and modelling your software, for a good reason. Not only the programmers will understand them but also the management and clients. Storyboards (GUI-screen-shots with functionality description) also help a great deal here.

InformationIsBeatiful is a great example of how you can abstract very complex things, numbers and tables into easily understandable diagrams.

1
  • Be careful, though. Just as everyone thinks they can write, so everyone thinks they can design clear diagrams and illustrations. Most people are wrong. Presumably you are a writer because your verbal skills are strong. Team up with someone with equally strong visual skills.
    – kindall
    May 2, 2011 at 22:20

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.