Technical Writing: Layout Tips

Once you have a clear sense of audience, purpose, and context, you can apply the following principles to enhance communicative competence of your documents:

technical writing1) Typographic devices — boldface, italics, shading — highlight items in a text and help the reader locate main sections.

  • Use bold text sparingly to create emphasis.

Too much bold text dilutes the effect.

  • Use italics for emphasis or to show irony.

The document has been proofread three times.

  • Use exclamation marks and underlines with purpose. Underlining web pages can cause confusion because hypertext links are often underlined.

This information is important or important works well;                                            important!!! does not.

2) Use colour to create order in a document.

Effective use of colour can help the reader identify recurring themes, titles and subtitles, and reveal information patterns and relationships. Use colours to:

  • Accomplish specific goals
  • Prioritize information — readers go to “loud” colors first
  • Identify a theme that recurs
  • Code different symbols or sections

3) Use white space to organize information into themes.

Used effectively, white space can enhance your documents communicative power. Use it to:

  • Create vertical or horizontal spaces
  • Space out information and prevent overcrowding
  • Keep together design elements that are related
  • Isolate and emphasize key information

technical writing

Basics of Technical Documentation Development (Part 1)

Technical documentation comes in many styles and formats, depending on the medium and subject area.

scientific discoveryWhile print and online documentation may differ in various ways, it usually adheres to the same guidelines for prose, information structure and layout.

Documentation Style Guides

Usually, technical writers follow formatting conventions described in a standard style guide. In Canada, most technical writers use The Canadian Style; in the US, technical writers typically use the Chicago Manual of Style.

Many government agencies and companies have internal style guides that cover specific corporate issues such as logo use, branding, and other aspects of corporate style.

Formal Development Phases

A technical publication’s development life cycle typically consists of five phases, coordinated with the overall product development plan:

  • Phase 1: Information gathering and planning (includes target audience profiling)
  • Phase 2: Content specification and user task analysis (analyze tasks based on target audience and information architecture)
  • Phase 3: Content development and production (develop/prepare the document)
  • Phase 4: Technical evaluation and editorial reviews (project management reviews the document)
  • Phase 5: Formatting, design and publishing (publish the document)

Related articles:

technical editing

Scientific Discovery and the Idea of Freedom

Traditionally, we envision the concept of freedom in two ways: as negative freedom, in the sense of lack of constraint on what science can do or be; and as positive freedom, or the power science has because of what it does (or the truth it tells).

scientific discoveryA third conceptualization of freedom in science has emerged in the last few decades: freedom as the power to transgress the limits of what science is presently capable of being or doing, rather than merely the freedom to be or do those things.

That is, a real and dynamic – rather than merely ideological and abstract – possibility of overcoming the stupor of memory, identity and history, all of which, due to their inherent tendency to conserve that which is by its nature fluid, infantilize its subject, in this case science.

But what exactly does it mean to transgress what we are capable of being or doing? And how can we accomplish that which by definition we are incapable of undertaking and even imaging at this moment?

Let’s see.

Suppose I hide a coin in my pocket. I then look for it again and find it in the same place. What have I accomplished in my search? I have indeed discovered a reality, but it is a reality of little value, a thoroughly anthropomorphic and self-centered reality – I have merely found that which I’ve set myself up to find in the first place.

Yet this is precisely how matters stand with regard to our understanding of scientific freedom today: We set up science as a trusty scientific method (or worse – a set of facts), as something that is in principle in hand, controllable.

We believe in a kind of benign, domesticated version of what is a profoundly violent act capable of destroying entire social and cultural orders.

If we are serious about science, however, must we not find, instead, the highest horizon of science sovereignty to be a space in which the questions of freedom and its limits do not arise at all – where the freedom of science, if effectively practiced, is so radically unpredictable that it can never be contained by culture, custom, laws and regulations? The point at which science becomes an explosive, unpredictable form of art?

While we may well agree that practicing such radical scientific discovery is important, for most of us – and certainly for our traditional social institutions – scientific freedom does not mean transformation in any deep sense. It merely means re-description – a change in how we think about what is going on and who we are – for we take a change in knowing, language and narratives that describe the world as enough to ensure change in fact.

This popular position on science, however, is extremely weak because our cultural, social, economic and media structures turn conservative not at the point at which they stop science from expressing itself, but – and precisely to the contrary – at the point at which they force it to express banal truths.

In other words, the very way we tend to conceive of radical possibility for change – evident in how we practice knowing, storytelling and symbolic representations more generally (e.g., the media and governmental portrayals of science, culture, politics, etc.) – all but ensures stagnation.

Yet perhaps starting to dawn on us today is the fact that real change is never about interpreting reality; instead, it forces itself upon us, unrecognizable and unexpected, as a new reality. And in so doing it presents us with a radical wager: exercise the freedom to transgress the status quo and experiment thoroughly with the unknown and the unknowable, or become irrelevant.

Related articles:

scientific discovery

Plain Language Layout

plain language layout

Strong layout have always been an integral part of design, but recent trends show a decisive shift towards cleaner, more efficient designs. Here are a few basic layout tips:

Number of characters: Readers have difficulty reading at a normal speed if there are more than 65 characters per line. Change your font style or size, or type of layout, to accommodate this fact.

Justified margins: Justified right-hand margin decreases readability because it causes the eye to stop at irregular spacings between words. Keep the left margin justified and the right margin unjustified.

Capitalized words: A short header in all caps is fine, but anything longer makes the text difficult to read. There are many other ways to emphasize important information: sidebars, infographics or changing the type or size of font.

Descriptive headers: Headers are effectively a table of contents for your documents; they contextualize information for the reader. This helps the reader to understand information more quickly, but also understand the structure, or the relationship, between message components.

White space: It can make your presentation shine, or it can make it appear cluttered and busy. Use white space skillfully to make subtle and expressive connections between meanings.

Related articles:

plain language layout

Re-thinking Science Communication in Plain English

We all know, or at least have a hunch: abstractions don’t explain — they themselves need to be explained.

A word — whether a pompous scientific term like Micropachycephalosaurus (a dinosaur) or a more over-the-counter and down-to-earth Acetaminophen — is not the thing it is pointing at. It is an abstraction, a signpost.

In fact, the thing itself, say a real-life aspirin pill — the stuff you actually ingest — is of a very different order than the word “aspirin”. It’s not just that the word is not the pill, it’s that the collection of elements that are put together to do what aspirin does have no inherent name at all.

re-thinking science communication in plain english

“This is not a pipe.” — Rene Magritte

In other words — and perhaps obviously — all names are made up. So even though we think we know how the pill works, how to manufacture it, what it does to the body and so on, our concept “aspirin” cannot capture the actual experience — whether the physics, chemistry, biology or everyday perception — of what we refer to as aspirin.

A thought experiment might make this more obvious.

Think of a definition for the word dog, one that would fit every particular case of dog, so that someone from outer space who has never even seen a canine could take your definition and use it to establish whether each and every creature they meet on Earth is a dog or not.

“It has four feet, furry tail and barks.”

Okay, good. But surely there are quite legitimate three legged, mute mutts that the alien would miss if he were using this definition (and if you tightened this rather broad definition, he’d overlook even more dogs), not to mention that he would mistake for a dog many barky Siamese cats and chatty hyenas.

The most important point of all though is the fact that he would miss dogs that you yourself would have no problem recognizing as dogs even though they do not fit your very own definition!

Do you see the problem?

In just the same way as you pretty much always intuitively understand but can never define your experience of a dog, you cannot define the experience of aspirin, the taste of sugar, nor what it feels like to be you, even though you intuitively know all of these.

This is because all concepts are always already abstract and general, and all experiences are always concrete and particular.

What this means, counter-intuitively, is that what we usually take for a fact — “this is aspirin” or “this is a city street” or “this is evolution” — is simply our concept about what we feel we understand, and not the understanding itself.

The reason all this matters is that it brings into sharp relief the fact that science doesn’t just discover facts — it deals in conceptual frames of reference (theories) as much as it deals in facts. It creates and re-creates understandings — by moving from the empirical to the conceptual and back– around what is considered to be valid empirical evidence at any given time.

This is called, in general, experimentation, though no scientist has ever actually used the scientific method in general — by its very nature experimentation is varied, always particular, and often downright peculiar.

What does this have to do with science communication?

Great science communicators, like great scientists, also proceed from the empirical to the abstract, asking themselves on behalf of the audience: “What problem does this theory or innovation respond to — what is the specific problem it solves?” or “How does it re-frame the problematic or take us past some difficulty?” or “What new problem does it make possible?”

Strong science communicators always think in terms of and work from the empirical problem to concept-theory, which enables them to explain the need for introducing made up scientific abstractions in the first place.

Weak science communicators, on the other hand, rarely leave the concept-level and so tend to write as if what is merely an abstract idea is true in fact — also known as reification of the abstract — and thus become enamoured with explanation: “How does this theory explain time?” or “What does the theory say about evolution?” or “What is a human being?”

These bad or static science questions presuppose that we already understand the object of inquiry by treating as real what is merely speculative or conceptual — aspirin or dog, in our first examples, time and evolution above. And then proceed to explain scientific findings as if the concept was experience itself, and science was merely a question of measuring or inventing these by this time merely mental or abstract objects.

See the difference?

Always proceed from the actual problem — whether conceptual or practical — to the science (the abstract) and not the other way around. This means that when doing science communication we must not try to “explain the science”, which is how science communication is often understood and approached, but to explain actual experience — hearing, seeing, touching, tasting, etc. — using science.

Related articles:

re-thinking science communication in plain english

Understanding Science vs Philosophy Debate

If the recent spate of public debates about the relationship between science and philosophy is a prime example of “science by press conference“, it’s also a chance to re-evaluate what we think the issue is about.

Some of us — Stephen Hawking, for example — claim simply that “philosophy is dead”; others, like Lawrence Krauss, argue that philosophy is irrelevant to science; still others, like Daniel Dennett, believe that philosophy can play a role in helping science to understand itself – a task which lies outside the scope of science proper.

philosophy vs scienceBut do all of these commentators have the same thing in mind when they say “philosophy”? Could it be that they are all on to something? Let’s see.

It is generally agreed that modern philosophy of science comes to its own with Kant’s “Copernican Revolution” in philosophy.

Put in basic terms, Kant realized that the way in which Western philosophy – from Plato to Aristotle, from Descartes to Hume – was traditionally set up assumed that the world as it appears to us (the subjective empirical) and the world as it is in itself (the objective, or Ideas, or that which is always already outside of our experience) were mistakenly assumed to be essentially, rather than just formally, different.

Kant further realized that when we try to reduce the subjective to the objective (as in Descartes’ “I think therefore I am”) or the objective to the subjective (as per 18th century British empiricists – Hume, Locke), we end up reintroducing the above-mentioned problem in more and more subtle ways, and so persist unable to account for our dual status as at once both the subject and the object of experience.

Kant’s ingenious recasting of the theretofore dogmatically conceptualized subject-object relationship — here Kant famously credits Hume for “interrupting my dogmatic slumber” — all but destroyed the traditional way of philosophical thinking.

In effect, since Kant’s “Copernican Revolution”, philosophy is no longer interested in speculating about what is on the other (objective) side of experience – since nothing at all can be said about what is wholly outside of all possible experience — but in outlining the objective conditions of possibility that must be satisfied so that this or that subjective experience can be what it is (for Kant, these conditions are time, space and causality).

In other words, up until Kant we thought that knowing (or Ideas) was derived from external objects (from things, events or thoughts), and Kant is the first to show that all knowing is dialectical, or process-dependent.

Kant further shows that the knower (the mind) and the known (objects and Ideas) cannot be conceived of as essentially different, either from each other or from the process of knowing, because they are not only two forms of the same substance (knowing in-itself), but are in a causal relationship only in so far as the mind is able to construct, rather than perceive, such a causal relationship.

Now different scientists and philosophers articulate this subject-object co-dependency differently — and even today much valuable work is done to further clarify the concepts of causality and objectivity — but all serious modern thought is structurally “post-Kantian”, in that common sense “Naive realism” is no longer seen as a reasonable position.

(This is roughly analogous to how all modern space science is post-Copernican, in that no one believes that the Sun revolves around the Earth anymore, even though we now know that Copernicus’ calculations were incorrect and we have more sophisticated tools to explain his assertions.)

If we now take this “post-Kantian” understanding of philosophy – philosophy as a science concerned with exploring the necessary conditions of possibility of experience (rather than with experience itself, which is the domain of science proper) – we will see that, in a way, all of the commentators mentioned at the outset are correct.

That is, the objective interest of philosophy (the conditions of possibility of experience) is different than the objective interest of science (empirical experience itself), so in this sense there is no competition or overlap; indeed, science and philosophy are not only about different things, but about different kinds of things.

It is also clear, however, that since the subject expertise of philosophy is the structure of thought as such, its insights can be quite helpful to scientists who must use thought as a tool in their attempt to understand the empirical world.

As for the alleged death of philosophy, in some ways at least Stephen Hawking seems to be right indeed — philosophy as a capital “T” truth-yielding enterprise is and has been long dead.

That’s because we now seem to understand that all of our descriptions of experience – including what happened before anything at all happened – are symbolic constructs, or abstract objects, that are either conditionally useful or not useful, but never unconditionally true or false.

Still, in so far as Kant was right — and we accept that the structures of experience, understanding and reason are inextricably interrelated — we must also concede to philosophy an expertise in the formal structure of thought, and indeed use it to inform theory-making in science.

Related articles:

philosophy vs science