Guidelines for JOMA Authors - Writing Style

Author(s): 
David Smith and Kyle Siegrist

Persons in the Dialogue

Popular bumper sticker:

Eschew Obfuscation

That's our goal. The so-called "scientific" style of writing is not more "objective" – it's dull, obfuscating, and not even particularly scientific. It has probably happened in JOMA, but we're working hard to stamp it out.

In particular, you (the author) are the First Person in this dialogue with your readers. If there is only one of you, you should show up as "I", not as a royal or impersonal "we". If there are two or more authors, you can be personally "we". You should never appear as "the author".

Your reader (most likely a college faculty member or student) is the Second Person – so address him or her as "you" – not as "the reader". You don't get to hear the reader's thoughts or words, but they will be there if you're holding up your end of an interesting conversation. Use the active voice as much as possible – agents actively doing things (including yourself) are much more interesting than things just happening.

While you're addressing the faculty, students can be Third Person – but in materials intended for students, they become Second Person, and your dialog is with them. Note that this not only makes for more interesting reading, but it also pretty much eliminates gender issues – and the remaining ones can be dealt with by keeping your Third Persons plural.

Example 1

An opening paragraph as the author first wrote it:

The aim of this paper is to describe a new type of web document that recently made its appearance at the New Mathwright Library and Café and to discuss it from two perspectives: from the point of view of its readers (students of mathematics), and from the point of view of its prospective authors (teachers of mathematics). These documents are called Mathwright Microworlds. A Mathwright Microworld is an HTML document (web page) that an author may create with any handy HTML editor that has a Mathwright "portal" embedded in it.

As we published it after revision -- now two paragraphs:

I describe in this paper a new type of web document -- the Mathwright Microworld -- that appeared recently at the New Mathwright Library and Café. I will discuss the Mathwright Microworld from the points of view of both

  • its readers -- typically students of mathematics -- and
  • its prospective authors -- typically teachers of mathematics.

A Mathwright Microworld is an HTML document (i.e., a web page) that an author may create with any handy HTML editor. The document becomes a Mathwright Microworld when the author embeds a "portal" that he or she creates independently with the Mathwright32 Author program.

Notes: The author is now the subject of the verbs "describe" and "will discuss" -- the agent of the actions. In the second paragraph, "author" (of a Microworld) is in the third person because there is no reason to think that the reader might be that person. Also, the revision resolves confusion about where and how a portal gets embedded.

Writing style: Paragraph structure

If you have a lot of long, intimidating "paragraphs" (in the sense of text between paragraph breaks), this means you're trying to make too many points at once. A well-formed paragraph has only one point (not necessarily in the first sentence – it could be almost anywhere), and the other sentences in the paragraph are "to the point". If you can't identify the point sentence – or you see more than one – then you need to think about restructuring.

Example 2

In Example 1, the submitted text, which looked like a paragraph, did not have an identifiable point sentence. The revision separates two points -- what the paper is about and what a Mathwright Microworld is -- into two short paragraphs. Each paragraph has only two sentences, and in each case the first sentence is the point sentence.

Example 3

The following text is from page 3 of the same paper as that cited in Example 1.

Imagine that you are creating a mathematical web page about epicycloids. You put careful thought into its design, and you decorate the page with instructional text, pictures, forms, hyperlinks, and whatever other HTML gadgets you find useful for telling your story. You then have a hypertext mathematical story with the additional important property that it is linked to a vast collection of other mathematical stories on the World Wide Web. You make the observation that a certain geometric construction yields a family of curves parametrized by a and b:

Equation1,

Equation2.

But something is missing. Readers cannot do experiments or ask "what if" questions. The demonstrations and arguments are as static as they have always been in mathematics texts -- perhaps more colorful, but still static. A student may ask "What does the graph of the cycloid look like if I make the a parameter negative instead of positive?" Unless you have provided an example, or a pointer to a page that has one, the student will not learn the answer here. HTML was not designed to provide the support you need. The equations above are only a picture with no "life" or meaning in the page. What you want is an added dimension of interactivity.

Notes: The displayed formulas create an ambiguity about whether this sample is one paragraph or two. If we interpret it as one paragraph, the point sentence is clearly the last one, and everything else is building up to this conclusion. If it is really two paragraphs, then the last sentence is still the point of the second one, and the "But" sentence is a redirection from the straightforward assertions of the first paragraph. The point of that first paragraph is then stated in the first sentence. Either interpretation is acceptable.

As with other style and editing issues, we (the editors) will get the last crack at the text--but it's more likely to be your story as you want to tell it if you tend to these matters yourself. There's a lot more to consistently writing good paragraphs-- e.g., the new information in one becoming the old information that leads into the next--but this will take care of itself if you think about the flow of the narrative.