In this note, we describe current policies for JOMA articles. These policies relate to document structure, writing style, reference style, mathematical notation and other issues of importance to JOMA authors, editors, and reviewers.

Publication Data

• Published 2002
• Revised May, 2006
• Revised September, 2006
• Revised February, 2007

Cover Page

Beginning in 2006, each article published in JOMA will have a standard cover page. The items on the cover page are as follows:

Authors

This section gives the name, affiliation, and a brief biographical sketch of each author of the article.

Abstract

An article should have brief abstract that describes the purpose and goals of the article in simple, non-technical terms.

Technologies

This section describes any special technologies used in the article, such as Java, Flash, MathML, Mathematica, or Maple. The reader can be given instructions on how to upgrade her browser or where to find required plug-ins. This section is very important. Some JOMA articles may only be accessible to readers with specific platforms or browsers, or to readers with specialized software. Such articles are fine as long as the reader is notified about the special requirements on the cover page.

Publication Data

This section gives information about the initial date of publication and the dates of any revisions that my follow. This section also gives copyright and permission information.

Navigation and Table of Contents

This section gives the table of contents of the article as well as any special navigational instructions. A JOMA article may well have a non-traditional structure with multiple threads or ancillary pages. Thus, a simple, linear table of contents of the sort found in printed documents will often not suffice.

Keywords and Subject Classifications

Keywords and subject classifications are important search features that were implemented in mid-2004, and their selection has largely been left to the editors. Authors are asked to suggest their own keywords and subjects. The list of keywords cannot exceed 255 characters. Subjects are restricted to those found in the subject search field and may be specified by number only.

For clarification of what is included in each subject, see the Subject Taxonomy. Only the top two levels of this taxonomy are represented in the subject search list. A given article, module, etc., may be listed with as many subjects as necessary.

Example 1

The article Special Relativity and Conic Sections  has the following subject classifications:

• 3.0 Algebra and Number Theory
  • 3.2 Linear Algebra
• 5.0 Geometry and Topology
  • 5.2 Plane Geometry
  • 5.3 Solid Geometry
  • 5.4 Analytic Geometry
• 10.0 Applied Mathematics
  • 10.1 Mathematical Physics
• 11.0 Mathematics History

Its keyword list is

• ellipse
• conic section
• focus
• directrix
• locus
• hyperbolic geometry
• space-time
• special relativity.

Thumbnails and Descriptions

When new items are featured in JOMA, they are presented with a short description and a thumbnail image. For the first year or so of the new site (mid-2004 to mid-2005), the thumbnails and short descriptions have mostly been created by the editors. Authors are welcome to create and submit their own. A thumbnail should be a 70x70 pixel (max) PNG, GIF or JPG image that is eye-catching and related in some way to the article, module, etc. Since line drawings do not reduce well to that size, a thumbnail may need to be created from scratch. Photographs are OK, and they scale better from larger sizes. The image might be a full-resolution segment of a figure in the work, obtained by cropping – this can be effective if the segment piques the reader’s curiosity for seeing the full image.

Mathematical notation has always presented a special problem for authors of web articles, since HTML provides only very limited mark-up for mathematics (mainly the tag for a variable, and the and tags for subscripts and superscripts. Here is a sample mathematical expression rendered with basic HTML:

y = a₀ + a₁x + a₂x²

For an article with relatively simple mathematical notation, these basic HTML tags may be sufficient. If not, there are a couple of approaches that JOMA authors can use:

MathML, the Mathematics Markup Language is an XML language that provides a very complete specification of mathematical notation. MathML is an open source, W3C standard and is now supported by the Mozilla Firefox browser and by the latest versions of Internet Explorer on the Windows platform via the free the MathPlayer plug-in. Moreover, in keeping with the best practices discussed previously, MathML encodes the structure of the mathematics much more completely than previous mark-up languages (such as TeX). Because of this, mathematical expressions in MathML can be imported from one MathML-aware program (an HTML document, for example) to another (Maple, for example). On the downside, MathML is difficult to author without special editing tools (precisely because so much information is encoded), and MathML is not supported on older browsers. Without a doubt, however, MathML is the future of mathematics on the web. In spite of the difficulties, a major goal of JOMA is to promote and encourage its use.

Another approach is to convert mathematical expressions into small graphics (typically in the PNG or GIF format). The graphics can be created with special tools (such as MathType) or with special converters (such as TeX to HTML). Remember, however, that "best practices" would require alternate text-based descriptions of the mathematical expressions also (in TeX or MathML, for example), attached via the alt or title attributes of the tag.

For more information on writing mathematical expressions in HTML and in MathML, see Mathematics with Structure and Style

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:

,

.

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.

As noted earlier, the most likely reader for an article is a college mathematics faculty member – even if the reader's response to the article is to say, "I need to point (some of) my students to this article." The same applies to articles in the Developers' Area.

The most likely initial reader of a module or a mathlet is also a faculty member, but the body of the module or mathlet must be written as though it is intended to speak directly to a student. That is, a module or mathlet should be student-ready so its initial readers can just assign it to one or more students. Material intended for the instructor only should go in a separate document, the Instructor's Notes (or Notes for the Instructor or whatever). This separate document will be linked as a pop-up from the front page.

Example

Design of a Thrilling Roller Coaster is a module (or series of modules, depending on how you look at it) that has a For the Instructor link on the front page. Apart from that pop-up page, the text is consistently directed toward student readers.

Format

Over the lifetime of JOMA, we haven't been entirely consistent with this, but we're settling now on an APA-like style for references. The in-text reference should take the form "(last name, date)" or – if the author's name is part of the text – "last name (date)".

Example 1

• ...  a paper entitled "Multigrid Graph Paper" (Bevis, 2002 ) ...
• ...  a means of streamlining the Lay (2003) presentation ...

In the reference list, it's the same order: "last name, initials [and other authors, if any, in same order] (year).", followed by the usual bibliographic information – but not repeating the date. If the list is already alphabetized, the numbering is redundant – and a nuisance if you stick in a new item. Also, the name and date are more informative within the text than a single number (math style) would be. Where the same author has more than one reference in a single year, use a, b, … after the year. And you can use "in press" or "in preparation" in place of a date for items not yet published.

Example 2

1. Carlson, D., Johnson, C. R., Lay, D. C., & Porter, A. D. (2002). Linear Algebra Gems: Assets for Undergraduate Mathematics. Washington, DC: Mathematical Association of America.
2. Meel, D. E. (1999b). Learning logs: Enlivening elementary linear algebra. PRIMUS, 9 (3), 205-225.

Online references follow the same format but include an explicit URL (with link to the same URL, opening a new window, i.e., target= "_blank") and a parenthetical "accessed (date)" to show when the resource was known to be available. (The date may get updated in the editorial process.) Variations are permissible -- in fact, the actual APA style for electronic references is slightly different -- as long as all the essential information is present, and the style is consistent within the document.

Example 3

1. Meel, D. E. (1999a). A linear algebra activity: From bases to matrices. MAA Online -- Innovative Teaching Exchange [On-line]. Available: /t_and_l/exchange/ite4/insearch.html (accessed 5/16/05)

Try to concentrate on resources that are likely to be both stable and correct. For example, class notes on an instructor's private page are not likely to have been vetted by anyone, and they may not last beyond the course offering.

The examples on this page are from a paper that would appear this way in a Reference list:

1. Meel, D. E., & Hern, T. A. (2005). Tool Building: Web-based Linear Algebra Modules. Journal of Online Mathematics and its Applications, 5 [On-line]. Available: http://www.joma.org/jsp/index.jsp?pa=content&sa=viewDocument&nodeId=560&bodyId=844  (accessed 6/10/05)

We are not sticklers for absolute compliance with APA style as long as consistency is maintained throughout a given work. For example, the preceding reference could also be given as

1. Meel, D. E., & T. A. Hern (2005). Tool Building: Web-based Linear Algebra Modules. Journal of Online Mathematics and its Applications, 5 Available online at http://www.joma.org/jsp/index.jsp?pa=content&sa=viewDocument&nodeId=560&bodyId=844 (retrieved 6/10/05)

The changes are in order of second (and subsequent) author's initials, "available online", and "retrieved" instead of "accessed". Whatever variations are used in one entry should be followed consistently throughout the list.

Links

When the article or module is published, References will be on a separate page. In the References list, please add a named anchor to each item (e.g., first three letters of author's name), then link to this anchor from each citation in the text. That way, with a long list, the relevant item will show up at the top of the page (unless it's toward the bottom of the list, which we can't do anything about). Also, please make all those links open in a new window (target= "_blank"). The URL won't be right, but we will do a global replace on those, once we know the URL of the References page.

Example 1 (repeated)

• ... a paper entitled "Multigrid Graph Paper" (Bevis, 2002 ) ...
• ... a means of streamlining the Lay (2003) presentation ...

Note that a reference in the text to an online item requires two clicks to access – one to open the References page in a new window, then one to access the resource in another new window.