Global Coherence
Global Coherence
We have talked a lot about how to build sentences and paragraphs.
The problem here: how can we put those together to form a coherent document?
Global Coherence
In particular, we talked about how to structure an introduction.
Start with a shared context. Include a summary of the problem, and its cost. Give the main point or solution.
The Document
The document should have an introduction: either a very explicit introduction or simply a framing of the problem/solution for a less formal document.
End the introduction with the main point/solution. Don't want to spoil the ending? At least promise that it will follow.
The Document
Make sure your readers know where the introduction ends and the body starts.
That might mean simply having a clear change in writing between the intro (main point/solution) and the main content.
The Document
For technical documents, that probably means section headings. The heading should give the main theme of the section.
Don't want headings in the final document? Consider adding them in the draft, but deleting them when (finishing your) editing.
The Document
In the main body of the document, readers will look for themes introduced in the introduction. So… they the main themes should have been in the introduction.
You should repeat those themes through the document.
The Document
Consider one of our (unusually short) sample introductions:
Machine learning techniques are often useful for uncovering patterns in data. Unfortunately, the algorithms in machine learning are often too slow to be applied to large data sets, which makes them impractical. Dimensionality reduction techniques can improve performance of analyses and allow them to handle larger collections of data.
The Document
After that intro, I would expect to find sections/paragraphs with headings/themes like:
- High-Dimension Slowdowns: problems with big inputs
- Dimensionality Reduction Technique #1
- Dimensionality Reduction Technique #2
- Lower-Dimension Effects: can handle bigger data sets now
In-Class Exercise
Write the headings for sections that might follow the other example introduction:
Software development teams work together to meet the requirements they are given. However, employee time lost to handling changing requirements is both frustrating for them and expensive for the employer. The scrum development methodology provides a development strategy that manages changes in requirements and helps the development team work together toward a common goal.
Sections
Each sections of your document should have a similar structure: like a complete document in miniature.
Exactly how that's implemented will depend on the scale: a “section” might be a single un-titled paragraph, or a page worth of text with a heading.
Sections
Start the section with a mini introduction.
For longer documents, that might be an introductory paragraph. For shorter paragraph-length “sections”, maybe just the first sentence.
Sections
Remember the Cohension & Coherence topic?
[A paragraph should start with] a sentence that says what the whole thing is about.
That becomes the mini-introduction to a paragraph-length section. It's almost like Williams and Bizup know what they're talking about.
Sections
The section intro should have the same role as the document introduction: give the main point/theme/concept of the section.
Sections
In the body of the section, explore the concepts introduced. That's the same thing the section is doing for the overall document.
In the body, address those themes and refer back to the introduction as necessary.
Subsections
Subsections are just smaller sections and should have the same general structure.
Introduce the theme, then talk about it.
Paragraphs
We have previously talked about paragraphs: first sentence should introduce the ideas. The other sentences should have the same (or closely related) topic and expand on those ideas.
Of course, not every paragraph follows a neat formula (and neither does every section for that matter).
Paragraphs
As usual, these are heuristics, not rules. They may be broken, but it's probaby a good idea to think about why you're doing it.
For example, sometimes a paragraph will transition from one topic to another: it will start with a familiar idea, but bridge topics and make its point at the end.
Writing Structure
The advice from Williams & Bizup has been the same for the document, section, subsection, and paragraph: introduce the theme, then expand on it.
For the sentence, start with familiar information
advice has a similar feel.
In each case, the goal is to keep the reader oriented and understanding their place in the ideas.
Writing Structure
The document becomes a fractal: at each level, the reader is getting the same experience of starting with familiar context and building on that.
Content Relevance
Readers should also see how the parts of your document are relevant. What is that content actually for?
That might include:
- Provides necessary background.
- Gives a supporting point for the main thesis.
- Explains reasoning towards conclusion.
- Considers alternate points of view.
- ⋮
Content Relevance
When introducing a section/paragraph, the reader should be led to its purpose in the document.
Similarly, each sentence (starting by announcing a familiar topic) should clearly fit into the paragraph.
Content Order
What is the best way to organize your document's content?
We know we will have an introduction and some number of body sections or paragraphs. What is the best order for the body content?
Obviously, it depends on the content, but some options…
Content Order
Chronological order is often the most obvious: from the first thing that happen(s|ed) to the last.
You can signal this to the reader by starting with words like first
, then
, finally
, or by linking topic like as a result
or and then
.
Content Order
You may be presenting several supporting points for your conclusion. Possibly be explicit in your introduction: there are three reasons why…
.
Order might be somewhat arbitrary, but look for something the reader can follow: most to least important, least to most complex, etc.
Content Order
If you are making an argument, then a logical order may be the best.
Here, you would go from premise to conclusion, or example to generalization, or assertion to contradiction.
Content Order
When ordering parts of a document, think about an order that will make sense to the reader.
The easiest order is “the order I thought of them” but that's probably not interesting to the reader.
Example
A white-paper from LoaPost, E-mail to go: Solving e-mail mobility problems.
In-Class Exercise
Think about the main topics/points/sections in your Assignment 1 description of HTML templating systems. (Pick one of the three versions of the document.)
Imagine you were going to re-write and were giving headings to each section (and subsection if you want). What would the headings be?
Diagnosis
Some things to check to make sure your document is coherent:
- Draw a line after the (document's) introduction. Is there a clear distinction the reader will notice?
- Divide the main body of the document into logical sections. Are there headings, or will the reader notice the logical breaks?
Diagnosis
- Circle the introductory segment of each section. Will the reader figure out what those are for?
- Does the introductory segment outline the main point/theme near the end?
- Do the parts of the body expand on things from the introduction?
Global Clarity
Williams & Bizup offer this rule of clarity, which isn't so different from earlier heuristics:
Readers are more likely to judge as clear any unit of writing that opens with a short segment that they can easily grasp and that frames the longer and more complex segment that follows. Williams & Bizup, 11th ed, p. 120
Global Clarity
In sentences, this meant starting with a familiar context. It was easy in simple sentences.
For example, we assume here that the reader knows about running times, and needs to know when they matter.
Running times are most relevant when working with large data sets.
Global Clarity
For more complex sentences, we tended to start with the main point which contained the subject and main verb.
[Rails] is designed to make programming web applications easier by making assumptions about what every developer needs to get started. Getting Started with Rails
Global Clarity
Another example, where I attempted to get the subject, verb, and object early:
An algorithm that might have been fairly efficient when the array fit easily in RAM may become impractical when the size of the array to be sorted approaches or exceeds the available primary memory, so that (much slower) disk or swap space must be employed and the memory usage pattern becomes important.
Global Clarity
All of these have a short segment that they can easily grasp and that frames the longer and more complex segment
.
Global Clarity
This lesson should be applied to the larger document as well.
The document('s introduction) and section('s introduction) should start with something the reader can easily grasp, and frame the content.
Is This Boring?
All of the guidelines from the text (in this topic, and previous) have fairly tightly constrained our writing.
Will all of our writing be predictable and formulaic?
Is This Boring?
Answer 1: Maybe it will seem that way to the author, but not to the reader.
When you're writing, you know the point and how everything fits together. Your readers don't (as they're reading). They won't have the same reaction you do.
We have been trying to build documents that the readers can easily figure out. That may mean a familiar structure.
Is This Boring?
Answer 2: Since we're talking about technical writing, maybe we don't care so much.
Are you trying to win awards for literature? Me neither.
Have you ever thought this API documentation is structured too much like the last one I read?
Me neither.
Is This Boring?
The goal in all of these writing heuristics has been to make things maximally readable. For this course, we'll be happy with that.