: How can one make technical issues more accessible to a non-technical audience? Most of what I write is non-fiction -- technical books, blog posts on open source topics, political stuff, etc.

Vote Up Vote Down

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)

Vote Up Vote Down

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.

(0)

Vote Up Vote Down

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.

(0)

Vote Up Vote Down

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.

(0)

Vote Up Vote Down

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.

(0)

Vote Up Vote Down

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:

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

(0)

Vote Up Vote Down

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.

(0)

Vote Up Vote Down

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.

(0)

Vote Up Vote Down

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.

(0)