Tag Info

Hot answers tagged

16

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


9

Well, that's a complex question :P There's lots of different kinds of complexity, requiring different tools - a complex character is different than a complex setting; a complicated plot is different from a plot expressing a complicated idea. Here's some guidelines I can share, from hearsay and from experience. I tend towards SF/F examples; hope these are ...


8

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


5

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


4

I had an English professor once who advised me to write papers discussing a book "as if you were explaining it to a slightly stupider classmate who had also read the work in question." His advice is condescendingly worded, but the general theory is sound: take your complex idea and break it down into simpler pieces. Once you have your complex plot ...


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.


3

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


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


2

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


2

Dumb down is a phrase that conveys contempt for your audience: you're using small words and simple phrases because you believe that your audience isn't as smart as you are. That may be true, but you should ask yourself this: If the ideas in your complex sentences and unfamiliar words can be conveyed as well by simpler text, how good a writer are you? Rather ...


2

One popular tool is the Flesch-Kincaid Readability Score. See, for example, http://en.wikipedia.org/wiki/Flesch%E2%80%93Kincaid_readability_test. Basically this counts the average number of letters per word and the average number of words per sentence and runs these through a formula to come up with an "appropriate grade level" for the block of text. ...


1

I've seen this up for quite a while now and will take a stab at answering your question. However, the answer is much more complicated than the question. The simple answer is yes, Python is used to convert text to braille tags, and a LaTex package is used to print out the symbols. IF the brailler you are using is not designed for use with a proprietary ...


1

I love writing complexity in to a universe. Frequently my stories come with thousands and thousands of facets that have nothing to do with the story. I'll expound on something for a page and a half that no one cares about and isnt particularly interesting. and then I'll look back at what i wrote, rip it out, and just hint at it. This tends to leave the ...


1

Take a look at the work of Robert J. Sawyer and Terry Goodkind. Both authors tend to inject philosophy into the middle of plot. The complexity of the plot is substantial on its own as well. I have read critical reviews of both authors saying that their philosophical diversions are not appreciated, but I have yet to see them described as "inaccessible". ...


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


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.



Only top voted, non community-wiki answers of a minimum length are eligible