Archive for the ‘Technical Writing’ Category

One of my classes this semester is ebook creation, and our latest assignment was to make a manual (because this is a technical writing program). The finished product had to include a cover, images, and lists. I didn’t really have anything to write a manual for, so I asked on Twitter if anyone had anything they needed me to write a manual for. (We didn’t actually have to write one from scratch; I think most people just reformatted existing documents.) One of my friends said, “Life.” So I said, “OK!”

I pondered how to accomplish this without sounding like one of those “Everything I learned in life I learned in Kindergarten” posters from the 80’s. After a little reflection, I came up with the following.

You can download the epub of the ebook here. (“Ebook” is a generous term; it’s only a couple of pages, more like an “epamphlet.”) It’s free. An epub i is viewable with Adobe Digital Editions or Calibre, both of which are free downloads.

You can download the mobi of the ebook here. This one is for Kindle. The assignment was to create an ebup, not a mobi. But I think more people tend to read stuff on Kindle (also a free download), so I also made a mobi for you. I had to do the formatting manually, because I can’t figure out any way to get Jutoh to read any of my style sheets.

Hope you enjoy my little book!

This was a school paper. We had to review a style manual. I didn’t have experience with IEEE before this, so it was new territory for me.

IEEE Editorial Style Manual: A Review

Amanda White

[1]       IEEE. IEEE Editorial Style Manual. [Online.] Available:

  http://www.ieee.org/documents/ieeecitationref.pdf

The IEEE Editorial Style Manual is published by IEEE, which stands for the Institute of Electrical and Electronics Engineers, and is pronounced “eye-triple-E.” It is a set of editorial guidelines used for the IEEE’s Transactions, Journals, and Letters. These include scientific publications on a vast array of topics, from Aerospace and Electronic Systems to Plasma Science.

No date, authors, or historical information on this style manual is available. I have been in touch with the IEEE to see if they could give me some background information, but as of this post I am still waiting for a comprehensive response. The latest dates cited in the references examples are in 1997, but Webster’s College Dictionary, 4th Edition, was published in 2004, so the earliest it could have last been updated is 2004.

Contents

The manual is only eighteen pages long, referring users to the Chicago Manual of Style for issues not covered in the IEEE manual. It is divided into two sections: the main body of the manual, and an extensive citation guide headed “Editing References.” The main body is divided into seven topics: IEEE Transactions Editing Philosophy, Parts of a Paper, Body of a Paper, Other Text, Other Types of Papers, Editorial Style for Transactions, and Rules of Grammar. The Editing References portion contains instructions and multiple examples for: Periodicals, Books, Reports, Handbooks, Published Conference Proceedings, Papers Presented at Conferences, Patents, Theses and Dissertations, Unpublished, Standards. It also gives instructions for citing online resources, including websites, FTP, email, and telnet. This section ends with a list of common abbreviations of words used in references, and four pages of abbreviations for IEEE publications.

Organization

The manual is short enough that no table of contents is needed. The main body of the paper takes up less than five pages, with most of the rest given over to reference examples and abbreviations. The organization of headings and subheadings did not represent a clear outline, and at times I struggled to understand what I was reading about. One example of what appears to me to be outline dysfunction occurs on the first page. The second heading (page 1) is “Parts of a Paper,” which only includes the subheadings “Paper Title” and “First Footnote.” This is followed by third heading, “Body of a Paper,” which appears in the same heading level as “Parts of a Paper,” and contains subheadings “Abstract,” “Index Terms,” “Nomenclature,” all the way down to “References” and “Biographies.” Doesn’t the body of a paper, and all it contains, fall under the category “Parts of a Paper?” Why, then, was it given its own equal heading, leaving “Parts of a Paper” with only two introductory subheadings? Another place that I thought was strangely organized was the “On-Line Sources” section of the References guide. Instead of having subsections for email, FTP, websites, etc., each type of reference is given its own heading (Books, journal articles, magazine articles, etc.) with rules for citing it as online content, followed by clarification on how it should be cited specifically for email, FTP, websites, etc. I would have rather seen a subheading for each type of online media, or these online specifications included under the main entry for each type of reference. I should mention, however, that the manual claims these online additions are based on ISO and APA standards, so perhaps they borrowed the layout of the information from one of those sources.

Examples of style choices

Spelling The IEEE manual refers users to Webster’s College Dictionary, 4th Edition, for spelling, and makes no spelling specifications of its own. It does, however, make extensive lists of acceptable abbreviations, such as “cybern.” for cybernetics and “proc.” for proceedings. The biographies section also lists abbreviations for international degrees, such as Dipl. Ing. and Diplom-Physiker, but does not give translations for these, explain what they stand for, or even list which countries or languages they are from, so I imagine this list to be impractical for most people to use.

Number use Numbers in the tens and hundreds of thousands should use “thin spaces” instead of a comma between the numbers. I had never heard of a “thin space.” I thought they might mean an “en space,” since the document referenced em and en spaces and dashes elsewhere. However, I looked up thin spaces in the Chicago Manual of Style, and they define it as a very thin space, one-fifth or one-sixth of an em space. But examples given in the IEEE Manual look more like just a regular, default space. I’m not sure if the author used the wrong term, or if the examples were originally printed with a thin space but the formatting was lost.

IEEE indicates that zeros should be used in front of decimals (which, I infer, are less than one but more than negative one), but not added to the end. That is, 0.25 is correct, but .25 or .250 are incorrect. I was curious as to how this stacked up with Chicago, so I looked it up. Chicago does not say anything about zeros tacked on to the end of decimals, but is in agreement with their inclusion before the decimal point, with the exception of firearm calibers and batting averages.

Capitalization The only note on capitalization in the IEEE style manual is for trademarks. After stating that symbols like ® and ™ are not to be used, it says that only the first letter of the trademark should be capitalized. I was puzzled by this at first. Did that mean that Coca-Cola should be written Coca-cola? But upon reflection, I think that they just meant not to put the brand name in all caps. Chicago is in agreement on both the interdiction on trademark symbols and the capitalization.

Citation Citations are where the IEEE stands out, visually, from other style manuals, with its numbering instructions: “Reference numbers are set flush left and form a column of their own, hanging out beyond the body of the reference. The reference numbers are on the line, enclosed in square brackets (page 5).”  Otherwise, differences between IEEE and Chicago are not glaring. Periodicals, for example, are structured similarly, but with a few differences: the placement of month and year information is later in IEEE than in Chicago; IEEE encourages abbreviations of periodical titles and months; and IEEE includes the abbreviation “vol.” before the volume number, where Chicago just states the number, letting the reader infer that it is the number of the volume. Here is an example taken from IEEE:

[2]       J. U. Buncombe, “Infrared navigation—Part I: Theory,” IEEE Trans.

   Aerosp. Electron. Syst., vol. AES-4, pp. 352– 377, Sept. 1944.

In Chicago style, this entry would appear:

2. J. U. Buncombe, “Infrared navigation—Part I: Theory,” IEEE Transactions on

Aerospace and Electronic Systems AES-4 (September 1944): 352-377.

Books are likewise similar. The only major formatting difference is that Chicago’s city and publisher info is contained in parentheses, and IEEE’s is not The only content difference is that IEEE requires the name of the country if the city is outside the U.S., whereas Chicago only requests it if the city name might be unfamiliar to readers.

An example from IEEE:

[2]       L. Stein, “Random patterns,” in Computers and You, J. S. Brake, Ed. New

   York: Wiley, 1994, pp. 55-70.

Translated into Chicago:

2. L. Stein, “Random Patterns,” in Computers and You, ed. J. S. Brake (New

York: Wiley, 1994).  55-70.

Other language variables: I was confused by a direction in the IEEE manual’s “Rules of Grammar” section (page 5) to “enclose parenthetic expressions between commas.” No example was given to clarify this. My first thought was that this meant that parenthesized comments needed to be set off by commas as well as parentheses, (like this), but as I had never actually seen that done anywhere, I was doubtful. After looking up the word “parenthetical” and learning that it does not necessarily require a phrase to be in parentheses, but can be applied to any sort of “aside,” I am leaning towards the explanation that IEEE prefers such comments to be contained between commas instead of between parentheses or em dashes. An example would have been helpful.

IEEE also states, “Do not use double parentheses in text expression, but keep them in math.” This is more or less in agreement with Chicago, which does not expressly prohibit nested parentheses, but “prefers” brackets, and does allow for nested parentheses where mathematics require them.

Conclusion

The IEEE Editorial Style Guide is short, sweet, and incomplete. I see it more as a style sheet to be used alongside the Chicago Manual of Style. I also see it as needing a revision, at least in its formatting. Additionally, it should be updated to include digital object identifiers, which are used extensively in Chicago’s 16th edition, but completely unmentioned in IEEE. Most importantly, I believe that it would benefit from examples given for all rules, not just for references. However, I do believe it serves its purpose as a style sheet for mathematic notation and specialized abbreviation, which are subjects that can be buried or incomplete in less scientific style manuals.

This was a report I wrote for the class Special Documents last semester. The assignment was to write a formal report about reports. I chose to narrow my focus to formality in language, and how it is related to but separate from formality in report style. The point of the project was more to follow all the rules about creating a formal report according to a chosen style guide. I chose APA, since I wasn’t familiar with it before starting this program. Of course, I deleted much of the front material (title page, letter of transmission) for the blog post, and WordPress is not taking too kindly to all my formatting, but I thought you might like to read it for the content. (It was my final paper and I got a perfect score, so yay!)

Abstract

Reports can be divided into formal and informal reports. The language used in these reports can likewise be divided into formal and informal language. This paper attempts to clarify that while informal language is usually used in informal reports, and formal language is usually used in formal reports, formality in language does not define the formality of the report. Language tone and report style can be considered separately, and on rare occasion, even mismatched.  Formality and informality in language are defined, as are formality and informality in reporting. Reasons are given as to why formality usually corresponds to report type. Finally, suggestions are given for occasions when formal language might be considered in an informal report, and informal language in a formal report.

Keywords: formal report, informal report

Formality in Language and Reports

A large portion of technical and professional writing is given over to the writing of reports. Although there are many kinds of reports, each with its own purpose and context, all can generally be divided up into formal and informal reports. Which of these two genres is at play depends largely on the structure of the report, but also on the language. There is not only a concept of formal and informal reporting in business, but also of formal and informal tone. While each is tone is normally assumed to be paired with its counterpart, structure and language are two different issues that can be examined independently.

Formality in Language

      Tone of language has to do with what words and grammar structures are selected for the report. These words are selected, either consciously or unconsciously, to make the report seem polished and professional, or simple and direct.

Informal tone can range from familiar to mildly casual. While the concept of “informal tone” encompasses slang, street talk, and even politically incorrect terms, in the field of business it is usually more a matter of minor word choices. Informal tone favors active verbs, rather than passive. For example, “Ms. Kiehl found the report on the coffee table” would be used, rather than “the report was found on the coffee table by Ms. Kiehl.” Informal tone welcomes the use of personal pronouns, like I and you. “I found the report on your desk” is acceptable when informal tone is being used.

Formal language, on the other hand, has a more limited spectrum. While some professional jargon may be included, depending on the audience, there is no room for slang and conversational voice. Here, the passive voice is favored, and personal pronouns are to be avoided. “I found the report on your desk” would have to be converted to, “The report was found by (author) on the desk of (recipient).”

Formality in Reports

      Formal and informal tone is one of the variables that make up formal and informal reports. A person who never reads or writes reports might assume that it is the only variable, but this is very far from the truth. Most of what defines the formality of a report has to do with the structure.

An informal report is structured very simply, often as a memo. It usually has an introduction, but that is its only feature outside the body of the report (with the possible exception of appendices, which may be included when necessary). They are usually intended for an audience within the organization, although anyone who has seen news reports of scandalous leaked memos or emails knows that they can reach beyond their intended circle.

A formal report contains what is called by the Handbook of Technical Writing (Alred, Brusaw, Oliu) “front matter, body, and back matter,” each of which contains some of several features (p. 195). “Front matter” may include title page, abstract, table of contents, list of figures, list of tables, foreword, preface, and list of abbreviations and signals. The body may include the executive summary, introduction, text and headings, conclusions, recommendations, explanatory notes, and references/works cited. The “back matter” may contain appendices, bibliography, glossary, and index (p. 196). Note the inclusion of “introduction” and “conclusions” in the body section, and not even at the beginning and end (respectively) of the body section. This goes against the expectation of those whose writing education stopped at the five-paragraph essay.

Why Formality in Language should correspond with Formality in Report Style

     Having shown that formality in tone and format are two different things, are they always mutually inclusive? Should they be? Does an informal report need to be written with informal language? Does formal language belong in a formal report exclusively? What happens when they are mismatched?

An informal report can easily contain formal language. However, informal reports are generally read quickly, rather than studied in-depth like a formal report would be. Using formal language can slow down the comprehension process, especially when it is not expected. An executive expecting to be able to glance over a memo and understand the situation might be annoyed at having to decipher unnecessarily formal language. Formal writing can add a layer of complexity that is usually unnecessary at the memo level, which can cause readers to expend extra time and concentration on the report, or give up on reading it at all.

Likewise, informal language can be inserted into a formal report, but not without consequences. Informal language can cause the report to be taken less seriously. It can lend an air of unprofessionalism to the project, which can affect the amount of support or priority it gets from your colleagues. As formal reports are often available outside the company at which they were written, this unprofessional aura can reflect poorly on your company. Additionally, a style that lands very far on the informal end of the tonal spectrum can often contain careless language that might offend some, which can lead to grave problems both in and outside of the company.

Possible Exceptions

      The reasons why formality and informality remain segregated are understandable. But are there ever times when they should mix? Are there times when formal language can be used in an informal report, and vice versa?

A formal tone in an informal paper is often an inconvenience. However, there are times when it might be helpful. If the writer is especially trying to seem more competent, educated, or even just a better writer (for example, when vying for a position on a writing project), adding a more formal color to the language can help characterize the writer in these ways. An informal report on a serious matter might benefit from formal language to remind the audience of the gravity of the issue. It must be stated that readability be considered first, however, and decisions to change the tone of the report should not interfere with this priority.

An informal tone is usually not polished enough for a formal report. Yet it should be considered that informal language causes the reader to feel more empathy and trust towards the writer. It is easier for the reader to see someone who writes as they talk as a human being. Formality can lead to trust because of its precision, but informality lead to trust because of its humanity. Informal language is also easier for most people to read, ensuring that the paper is properly understood; indeed, that it is read at all. Audience is the greatest consideration in the prospect of deformalizing the language of a formal report. The writer must consider not only the primary audience, but also everyone who will come into contact with the paper. What might be acceptable to the primary recipient might be taken out of context by other readers, casting a bad impression of the writer, the project, or the company as a whole.

Conclusion

      Formality in language is usually matched to formality in report style for many reasons, including audience, context, and purpose. Nonetheless, it should be understood by writers that formality and language and formality in reporting are separate issues, and can be considered separately, although normally used together. Although these styles can be mixed, the decision to do so must be made under careful consideration.

List of Sources

Alred, Gerald J., Brusaw, Charles T., & Oliu, Walter E. (2009).  Handbook of Technical Writing (9th ed.).  New York, NY: St. Martin’s Press.

Formal versus informal language. Language of Report Writing.  (2005.) Retrieved December 10, 2011, from https://www.dlsweb.rmit.edu.au/lsu/content/2_assessmenttasks/assess_tuts/lang_reports_LL/formal.html

Shook, R.  Types of Reports [Class handout, ENGL 6470, R. Shook, Utah State University, 2011].

Here is a little mini-project I did, that was actually a convergence of two tasks.

The first was actual homework. Our reading assignment for Reading Theory and Document Design class was the first three chapters in Shaping Information: The Rhetoric of Visual Conventions by Charles Kostelnick and Michael Hassett. Part of the assigned discussion topic was to draw out the categories of conventions the authors make, and discuss them.

The other was self-homework. In perusing Technical Writer job postings, I noticed that all of them require Microsoft Visio, which is used for making charts and graphs and stuff. So I was going to try to teach myself Visio, until I found out there is no Visio for Mac. Seriously? The closest Mac competitor is ConceptDraw, so my next plan was to teach myself that. Until I saw that there’s also something by ConceptDraw called MindMap, which seemed  a lot easier. So I thought that might be a good place to get started.

MindMap helps you make what we in junior high TAG writing class called “clusters,” but apparently they are called “mind maps” now. It’s the kind of brainstorming chart where you put a main idea in the center, and then shoot branches off it of related ideas, and shoot branches off of those. It’s kind of like an outline, when you’re not sure yet how the outline is going to be organized.

So, since the discussion topic was simple enough–categorizing based on the reading–I thought it would be a good chance to try out MindMap.

The version I had available to me was MindMap 5, and they’re up to 7 now, so it’s probably pretty out of date. So don’t expect this to be a very accurate software review. But it was a place to start.

The software was easy enough, though harder than I expected to customize. I thought there’d be more layers of levels, instead of just “main topic” and “subtopic.” So I had to graphically differentiate inner levels manually. It was a pain, so I only did it for the second level, and just let the 3rd and 4th be identical. The clip-art was a nice, fun touch, but the sizes weren’t (that I could see) variable, so they mostly just ended up making my graph spaced weirdly. But, as far as just plotting down my ideas, it was really simple. I wish I’d noticed before I’d gotten started that they had “themes,” as that would have been fun to play around with.

Anyways, I took my categories directly from the text, and included page numbers so my classmates can look them up and decide if they agree or disagree with the way I’ve included them.

Here’s my chart!

Sorry, that’s as big as I can get it on here, but the picture should link to a pdf file you can download, which is much easier to navigate.

Anyways, that was just my fun little project, thought I’d share!

This was my final paper for my Usability Studies class last semester. Because I had never had the opportunity to conduct or take part in an actual usability study, I decided to stick with what I knew. I’d been singing a lot of choral music at the time, and my colleagues and I were getting frustrated at the irksome little choices some of the publishers had made. I don’t think this paper will change the industry, but it’s been interesting hearing feedback from non-musicians who had never considered this realm of usability.

P.S. I got an A. 🙂

———————————————————-

Usability in Sheet Music
Amanda M. White

Submitted to Dr. David Hailey
Utah State University December 9, 2011

Imagine being surrounded by glorious music. Heavenly voices surround you on all sides, powerful, beautiful, lifted up in song. An inspired song, praising a benevolent being and moving to all who hear it.

Suddenly, in a heartbeat, the music turns sour. The harmonies crash into rough and uneven dissonances, clashing, until finally the voices tumble away into silence.

“Sorry,” a soprano pipes up. “Bad page turn.”

As a professional choral singer of fourteen years, this happens in rehearsal about once a month. In musicians’ jargon it is commonly called “train wreck,” or more gently, a “derailment.” Either way, the imagery is clear: we move forward, over hills and valleys, through tunnels and over bridges, until suddenly we are thrown off course and are unable to continue. This is understandable to even non-musicians. Music is hard, mistakes happen, we move on. But what non-musicians might not realize is that these mistakes are often caused not by difficulty in the music, but by the way it is published. Careless edits or space-saving shortcuts taken by music publishers, who might never view the final product—not the published manuscript, but the performance of the music—cause tangible setbacks to musicians trying to do their jobs.

In this paper, I’m going to examine some of the common problems caused by music publishing. I have chosen to focus on choral music, because it is one of the forms of written music (along with piano accompaniments) most likely to be sight-read.

What is sight-reading?
Sight-reading means that a musician, or a group of musicians, plays or sings an unfamiliar piece of music, without preparation, as written. It is to be distinguished from gradual forms of music learning, such as playing a two-handed piece one hand at a time, singing a piece on solfège or numeric syllables, learning the rhythm separately from the melodies and harmonies, or picking through a piece of music slowly and with starts and stops. To sight-read a piece of music means to pick it up, never having seen it before, and instantly perform it as close to perfectly as possible. It is akin to an actor doing a “cold reading,” picking up a script and reading one of the roles in a scene, without having studied or memorized the lines (sometimes without any background information on the character or plot). As one would surmise, it is a highly efficient rehearsal method, but requires excellent musicianship skills.

When singers work this way, the skill is more accurately known as “sight-singing,” although the term “sight-reading” is still more often used in the vernacular. Sight-singing has its own skill requirements apart from most instrumental reading. The absence, practically speaking, of a visible or tactile means of pitch selection means that singers must choose their tones mentally, rather than physically. A pianist, for example, who wants to play a B natural above middle C, can simply look at the piano and press the correct button. A singer has no “button” to look at or press, so they must either have perfect pitch (the vast majority do not), or mentally calculate what tone to sing by its relationship to notes preceding it. Additionally, sight-singing almost always involves reading text and music at the same time.

This is not to say that sight-singing is harder than instrumental sight-reading, as other instruments have inherent difficulties. Some instruments, such as pianos and harps, have to play many notes simultaneously; singers, while making use of the other lines of music, are only responsible for correctly singing one pitch at a time. Additionally, due to physical limitations, the addition of text, and the necessity of breathing (a handicap shared with wind instruments), vocal parts are usually less rhythmically complex than their instrumental counterparts. Rather, this is to point out particular problems sight-singers must face, as these will come up as we examine usability issues.

Lyrics not printed below each staff
The vast majority of choral music is sung with text, in English or another language (usually Latin or German in choral music). So not only does the singer have to accurately sing the notes and rhythms (with good technique), she must also accurately sing the correct words (with good diction). There are several inhibitors of this ability, the oddest being the occasional absence of text from below some of the vocal lines.

page from Pinkham's Christmas Cantata

Figure 1. Christmas Cantata by Daniel Pinkham. ©1958 Robert King Music Co.

In Figure 1, the Latin and English text is printed only below the soprano and tenor lines during the refrain. The altos and basses are expected to look above their lines for the text. During the verse, things become even more confusing. The alto line begins with lyrics, which then disappear mid-system. This is not a random occurrence; it has a logical reason, although I wouldn’t go so far as to call it a valid one. The two measures of alto text are printed because the altos are at that point singing such a different rhythm from the sopranos that their syllables do not fall on the same beats. For example, the sopranos are already to the “-te” of Jubilate, the fourth syllable, when the altos arrive at “-bi-,” the second syllable. In fact, the text between the two parts is not equal. The alto line skips two words, “Deo” and “omnis,” changing the translation from “Praise God all earth” to “Praise earth.” Scriptural integrity aside, it is clear that this setting necessitates texts printed for the individual lines. However, I would argue that the text should be printed for the individual lines throughout the score.

In Western music tradition, text is always placed below the music, with rare exception. It is as ingrained in a singer’s mind as a green light meaning “go.” This is true of opera, musical theater, and even sheet music for pop and rock songs. This is largely tradition, but it is also because the space above the line is needed for dynamic, tempo, and other musical markings. You can see “VERSE 1” printed above the first system of Figure 1, as well as “p” (piano) printed above the last system. (The piano marking is placed below the system at Verse 1, presumably because the space above the line was taken by the words “VERSE 1.”) While there is little chance of a singer mistakenly intoning “Verse 1” to the tune instead of “Jubilate Deo,” there could be more risk with longer notes, especially those written in the same language as the text. While I have yet to hear a singer accidentally sing “Flowing, with freedom” instead of the intended text, my point is that there is a reason for the template. Breaking from this template is a distraction that can cause errors.

In this particular edition, the deletion of the alto and bass lines is doubly problematic because of the bilingual text. The English printed below the Latin (in the same font and with no other distinction, a usability issue unto itself) means that when an alto or a bass looks to the top line for the text, their eyes will land on the English first. Pieces such as this are almost never done in translation (especially not if the original is such a universal singing language as Latin), so the edition would have been better off not including it at all. But since they did, it makes their decision to only include text on every other staff that much more problematic.

I’d like to invite the reader to examine, even measure, the spacing between the staffs in each system. The space between the soprano and alto staffs, the alto and tenor staffs, and the tenor and bass staffs, are all equal. The publishers are saving no space by leaving out the text between the alto and tenor lines, and there is clearly plenty of space below the bass line. The only gain is the extra white space, which in this case is not having any positive effect. It is not more “calming” and “clean” to look at when your eyes have to scramble to find the lyrics.

No measure numbers
The above score features a secondary problem: The measures are not numbered. Most choral scores will number the measures of each movement. If not every measure, usually at least one per line, or a few per page, are numbered, and the musicians can count forward or backwards from there to determine the number of the specific measure they want to call attention to. Either alternately or in addition to measure numbers, rehearsal letters or numbers can be included. This is especially common in larger works. Important landmarks in the piece are labeled, so that a conductor can say “Tenors, can I hear you at letter F?” Measure numbers, however, are much more useful, as they occur more frequently and allow for greater specificity. It’s easier for a conductor to count backwards from twenty-two and say “Go to measure nineteen,” then it is to say, “seventeen measures after B.”

This score contains no measure numbers whatsoever. It has occasional rehearsal letters, but only some are included in the vocal part score. Since the conductor’s score, containing all the vocal and instrumental parts, is laid out drastically differently than the vocal part scores, it is hard for the conductor and singers to communicate to each other about where in the song they are. The conductor will say something like, “Two before A,” but the singers don’t have “A,” so they don’t know where that is. The singers will say “Second measure, top of page two,” but the conductor’s page numbers are different. Problems like this are time-consuming, and easily preventable. It takes little space or ink to add tiny numbers to every few measures. In no circumstances should this sort of score be published without measure numbers, especially if rehearsal letters are not consistently included.

Dynamic markings only in the accompaniment

page from Palestrina's Canite Tuba

Figure 2. Canite tuba by Palestrina. ©1964 Chester Music.

A related problem to the above is a score that might have all the lyrics in the correct places, but reserves the dynamics, tempo markings, and other notes for the accompaniment. With the singers busy reading their own lines, the only person who sees these markings is the pianist (if there is one), conductor, and possibly the basses, since their lines are in proximity.

In figure 2, you’ll notice all manner of markings in the accompaniment. Starting with “poco rall.” (“slow down a little”) and a decrescendo (get gradually quieter) in measure 18, you will see dynamic markings (p, mp), tempo markings (poco meno mosso, a tempo), crescendi and decrescendi both independently and as hairpins (crescendo then immediately decrescendo), tenuto markings, and even a stylistic order, “brillante.” If you look up at the vocal parts, exactly none of these markings are included. The cherry on top is that this is an a capella piece. The “accompaniment” is not meant to be played, and is only a reduction of the above voicings for a pianist to play at rehearsals.

It can be argued that this piece, dated 1572, is from a time period where dynamics were not normally included, which means that the markings in the accompaniment are editorial, and thus only “suggestions.” However, I would argue that the publisher should make up their minds as to whether to include them, and stick to that decision. The score can be published with no markings, as most choirs and directors are capable of making their own artistic choices; or it can be published with them. To include them in only the piano part serves no one, especially when there is not actually a piano being played.

Half notes that look like quarter notes
Figure 2 also features another problem: half notes (which have empty circles) that are printed too small and with too thick a font, making them look like quarter notes (which have filled-in circles). Is is apparent from the singers’ pencil markings in the score that many people struggled with this problem. Some dealt with it by drawing empty circles near the note, such as in measures twenty-two and twenty-eight. A tenor in measure seventeen has sketched a half note above his pitch. Less legible (in this reproduction and in the original) are those who tried to draw an empty circle over the half note, such as the soprano in measure nineteen. Another soprano in the same spot tried to correct the problem by writing “1 2” and “3 4” over the two half notes, to remind herself that each note is worth two beats (half note), not one (quarter note). Most telling, a soprano at some point actually believed that the half note in measure twenty-five was a quarter note, thus causing a measure of 3/4 instead of 4/4 like the others. This is evidenced by the triangle written over measure twenty-five, which is a symbol for 3/4. Hopefully, she realized her misunderstanding by the time of the performance.

Tenor line in bass clef

Page from Gloria by K. Lee Scott

Figure 3. “Gloria in excelsis Deo” from Gloria by K. Lee Scott. © 2011 Birnamwood Publishers.

(Sorry, due to weirdness, the above image came out smaller than it originally was in my paper.)

Most people, musicians or not, had at least enough music education in school to know that there is a treble clef and a bass clef. (There are other clefs as well, but these are the most common, and the only ones singers deal with.) Sopranos, altos, and tenors usually sing in treble clef (the tenors an octave below), and basses and baritones (for the purposes of choral music, baritones are considered “first basses”) sing in bass clef. This applies to both choral and solo music. When you look at a four-staff choral score, you will see three lines of treble clef (the tenor one may or may not have a tiny “8” at the bottom to indicate the octave below, but if not, it’s implied), and one line of bass clef.

However, when you look at a two-staff choral score, you’ll see something quite different (first two systems of Figure 3). The soprano and alto voices are placed on a single staff, and the tenor and bass voices are placed on another. The soprano and alto voices are notated in treble clef, while the tenor and bass voices are notated in bass clef. Everything is fine here, except for the tenors. They do not usually sing in bass clef, and can get thrown off by the transposition, especially when a score toggles between two- and four- staff notation.

So why not have tenors learn bass clef in the first place, instead of treble clef? Tenor writing is really too high for bass clef. In two-staff notation, the tenor line often sits very high on the staff, with several ledger lines often necessary. As any coloratura soprano or flautist can tell you, the farther off the staff you get, the more brainpower it takes to recognize the note. Resisting the urge to comment on the amount of brainpower available to tenors, bass clef is simply not conducive to tenor music.

Essentially, reducing a choral score to two scores is “pianist think.” A pianist thinks in terms of what their two hands can play: two top voices in one hand, two bottom voices in the other. Though much of the time, the tenor part is closer in range to the alto than to the bass. But I think this sort of editing happens when choral scores are arranged by pianists, rather than by singers. Which makes sense: many, possibly most, composers and conductors are also pianists (and/or organists). While most know the basics of singing technique, few are highly-trained singers. So it’s easy to see why scores end up being published this way: it makes sense to the people writing and conducting the music, and is an efficient use of space. However, the mistakes it can lead to are not an efficient use of rehearsal time. Two-staff notation should be reserved for only the simplest music.

Changing number of staffs
In the third system of Figure 3, you’ll notice a drastic change in the way the score looks. Here, the layout has gone from two vocal staffs to four, solving our tenor problem. However, this change causes more difficulties than it solves.

The sudden shift in layout throws a singer’s eye tracking off-base. An alto who was singing the top line is suddenly on the second line. A tenor who was on the bottom line is now on the third line. It sometimes takes singers a measure or two to figure out what has happened, during which time they are singing the wrong part.

The tenor problem is even worse here, because the tenors are not only adjusting their eye tracking to a new line, but adjusting to a new clef. They have been singing in bass clef, and are suddenly in treble clef. A tenor who catches the change in staffs, but does not adjust for the change in clef, will try to make a sudden skip down to a C# (what the pitch would be in bass clef), instead of continuing up to an A (what the pitch is in treble clef).

This sort of switch is not only a problem on the page where it happens, but on subsequent pages. Every time a singer reaches a new page, they have to find their line again. This is normally easy, and done on an unconscious level. However, if the systems are changing back and forth from two to four staffs, it is easy for a singer to forget which line they are supposed to be on, and to sing the wrong line. This is not a problem for sopranos, who always sing the top line, or basses, who always sing the bottom line, but rather for the middle voices, the altos and tenors.

Fortunately, this score includes a note of redemption in the “warning” marks for the staff expansion. At the end of measure 20, before the staffs expand into four, there are “up/down” arrows, informing the singers to expect an expansion. While these small markings are easy to miss, they are better than an unprepared change, and will often reduce mistakes made. When expanding or reducing staff lines, it is very important to include this kind of signal.

Bilingual editions with conflicting note values

page from Vaughn Williams' A Choral Flourish

Figure 4. “A Choral Flourish” by Ralph Vaughn Williams. ©1956 Oxford University Press.

Classical music is an international art, and the texts set to music stem from many different languages. As most singers and audiences are not multi-lingual, publishers often try to reach a wider audience by including “singing” translations—that is, not word-for- word literal translations, which might not line up syllabically with the music, but a paraphrase of the text that fits the poetic meter of the original. Although contemporary practice usually encourages singing in the original language, there are exceptions. Singers in amateur choirs may not be familiar with pronunciation of foreign languages. The director (or, in the case of liturgical music, clergy) may be concerned with the audience understanding the text, especially in cases where program notes (with translations) are not distributed. Languages outside the standard “singing languages” of English, Italian, French, German, and Latin, may be too challenging for even professional singers, so pieces in Russian or Czech are often done in English translation. Generally, though, performing pieces in translation is a dying practice, and the English below the original usually goes ignored.

Singing translations would be a harmless inclusion, except when the translated text does not perfectly fit the rhythm of the original. This leads to different rhythms superimposed on the same staff, as seen in figure 4. This causes many rhythmic and textual errors to singers who are suddenly confronted with two different rhythms in the same measure. When confronted with the first measure of the bottom system of figure 4, singers are likely to make one of three mistakes: re-attacking the Latin syllable (“eee- eee-jus”), predicting the end of the word (this is a commonly sung text and singers are usually familiar with the words it contains) and jumping to the syllable “-jus” half a measure early, or dropping down to the syllable below the note and mistakenly switching into English before they realize what is happening (“ee– are done…”).

While most usability issues can be smoothed over by singers’ penciled-in notations, having extra notes in your measures is difficult to remedy. Scratching them out or trying to circle the proper note just adds clutter to the page. With this in mind, singing translations should only be included when they mimic the rhythm and meter of the original exactly, if they are included at all. (Exceptions can be made for choruses in full operas, which are often performed in the vernacular for theatrical reasons.)

What makes a “bad” page turn?
The most common complaint about printed music is the elusive “bad” page turn. Loosely, this means that a page turn occurs in a place that causes singers to make mistakes. But what exactly makes one page turn worse than another?

To put it in very general terms, a page turn becomes problematic when it immediately precedes something unexpected, that must be dealt with instantly. The fabric of music is patterns, lending an unconscious air of predictability that makes sight-reading possible. Melodic and rhythmic themes repeat, harmonies change and stabilize with certain regularity, time and key signatures are the norm. Of course if everything that happened were predictable, music would be boring. Hence the “surprises” that occur in our scores.

When these surprises occur over a page turn, we don’t have time to mentally prepare for them. The more drastic the change, the more likely mistakes are to occur.

First page of Pinkham page turn

(Page break)

2nd page of Pinkham page turn

Figure 5. Christmas Cantata by Daniel Pinkham. ©1958 Robert King Music Co.

Figure 5 is a good example of a page turn problem, as evidenced by the notations written in by the singers, at least three of which felt the need to actually write in their upcoming notes. This disconnect occurred for them because the notes that begin the next page represent a drastic change from what had gone on in the piece thus far. The rhythm changes from fast and syncopated to slower and on the beat, and the chords are effectively unrelated. The melody also features relatively significant leaps for the first sopranos, altos, and first tenors.

There is no simple solution for this. The only thing publishers can do is be aware of where the challenging changes are. And they are not always the same for every voice part. Sometimes the tenors might have a difficult page turn while the rest of the choir is silent. But if the problem spots can be located, an attempt should be made to not let them land directly on a page turn. Even one measure of buffer is enough to help.

Counting blank measures
The second measure of page six contains a figure that most singers are not used to seeing. The “5” over the horizontal bar means “five measures,” i.e., “five measures of rest.” So in the example above the singers are expected to count five measures of 2/4, then five measures of 3/4, and then one last measure of 3/4 for which a trumpet cue is given.

This method of short hand is the norm for orchestral instrumentalists, who often rest for long stretches of time in between entrances, and do not typically include any sort of accompaniment. It is very rare for singers, however, who typically have an accompaniment in their scores, whether it is a piano or organ part, or a piano reduction for a capella pieces. (Rarely do singers perform from full scores, i.e. “conductor scores,” which would be too heavy to comfortably hold and involve too many page turns. Chamber music is sometimes an exception.) Singers are quite unaccustomed to counting blindly in this fashion. Rather, they are accustomed to following along in the accompaniment, or other voice parts, while they are resting.

Most of the time, the biggest problem is that singers who don’t have perfect pitch need to find their entrance note based on what is happening before their entrance This score, though, redeems itself by including the trumpet cue before the entrance, from which the singers can find their pitches. Still, the problem remains that singers are just not used to counting music in this way. This is evidence to some orchestra members that singers are not as intelligent as they are, or are lacking in musicianship skills. In actuality, it is simply a matter of practice. Singers are so rarely asked to view music in this way, that doing so is disconcerting for them, and leads to confusion over their entrances.

This type of notation should generally be avoided. When it does occur, however, publishers should be extremely generous in the giving of instrumental cues. One measure of “warning” is not enough for many singers to orient themselves.

Are usability issues really to blame?
Singers are usually not as good at sight-reading music as classical instrumentalists, and when rehearsal times are short, mistakes are easy to come by. Are we using “bad page turns” as excuses for mistakes that are our own responsibility? To what extent are usability issues really to blame?

Usability issues don’t cause mistakes single-handedly. Simple music can be read despite most of the above problems, and more skilled readers can often avoid being tripped up by publishing pitfalls. The problems occur when bad publication practices collide with difficult passages of music.

For example, a quick change from four-staff to two-staff notation is perfectly manageable when the music is slow and simple, the singer already has an idea of where the music is going, and there are no other distractions. On the other hand, when sixteenth notes are flying by at rapid speed, tonalities are changing every other measure, and rhythms are surprising, a seemingly minor issue can stop the rehearsal.

Problems can also be compounded. A single usability problem might only trip up one or two people, but combined, they can cause musical train wrecks. Bilingual scores with conflicting note values are already challenging, but if it is also difficult to distinguish half notes from quarter notes, rhythmic accuracy becomes slippery.

What can be done?
Usability problems exist in printed music partly because of carelessness on the part of the publishers, and partly for convenience and cost-cutting measures. Two-staff writing is done because it saves paper. Omitting measure numbers is just laziness.

How much say does the consumer have in this? Unfortunately, not much. Directors choose pieces for the music, the text, or the composer. With the possible exception of anthologies, the publishing practices are rarely a consideration at all. Most pieces are only published by one company, so whoever wants to perform that piece pretty much has to put up with these minor issues.

More power, on the other hand, is in the hands of the composer. Composers with enough “clout” to shop their pieces around to different publishers can consider how well the company ranks in terms of usability. In fact, I find that it’s usually the composers who are most vocal in complaining about these issues. Although they may find that their sway in how their music is printed is limited, it is still more than that of the consumer.

Another option, one that is frequently performed, is for choirs to purchase the music, but operate from self-edited, photocopied versions. A conductor or his assistant can take the time to create a “master copy” from a published edition, adding in measure numbers and missing dynamics, whiting out text in the unused language, writing in missing lyrics, and rearranging the pagination to avoid problematic page turns. According to the Music Publishers Association Copyright Resource Center, this falls under legal copywriting: “Printed copies which have been purchased may be edited OR simplified provided that the fundamental character of the work is not distorted or the lyrics, if any, altered or lyrics added if none exist” (Copying Under Copyright). Presumably, this does not prohibit copying in the intended lyrics when they are omitted from a line of music.

Usability issues are often overlooked by publishers, who are not the ones who have to use the music. Meanwhile, they are interrupting rehearsals, thereby costing organizations money and interfering with our ability to make good music. Although it is not a simple situation for musicians to vote with their dollars, we can still make their opinions known to publishing companies. Other than that, I believe that the bulk of the work will fall to the composers, with the rest of us relegated to editing the scores we want to use ourselves. It is my hope that this paper will help us as musicians to consolidate some of our ideas about what we want and don’t want in printed music, and thus to make it easier for us to vocalize our collective preferences to publishing houses, as consumers, as composers, and as fellow music lovers.

References

Copying Under Copyright: A Practical Guide. (2004-2011.) Retrieved December 9, 2011 from http://www.mpa.org/copyright_resource_center/copying

da Palestrina, G. P. (Composer). (1964). Canite Tuba [Sheet music]. London: Chester Music.

Pinkham, Daniel (Composer). (1958). Christmas Cantata (Sinfonia Sacra) for Chorus and Double Brass Choir [Sheet music]. Paris: Alphonse leDuc Editions Musicales.

Scott, K. Lee (Composer). (2011.) Gloria [Sheet music]. St. Louis: MorningStar Music Publishers, Inc.

Vaughn Williams, R. (Composer). (1956.) A Choral Flourish [Sheet music]. London: Oxford University Press.

My ESL class

My ESL class, 2002

Because the grad program that I’m in is intended for people who are already professional technical writers, and I’m a musician, I like to joke that I “talked my way into” the program.

In reality, I discussed my situation with the head of the program, Keith Grant-Davie, who informed me that, because technical writing covers so many different kinds of writing and involves so many varied skills, they were pretty liberal about what they considered “prior technical writing experience.” Maybe I hadn’t been writing user manuals, but many of my magazine articles (the ones about technology, and the how-to’s) counted.

Technical writing is a field people enter from all kinds of backgrounds– from obvious ones like engineering and journalism, to those that are a bit more of a stretch, like education and music.

I thought it would be interesting to explore what skills from my previous jobs, and those of others, carry over into the field of technical writing. This could be helpful to some who are considering changing careers, or adding technical writing to their skill sets, but not sure if they are qualified or not. In the future, I’ll cover skills from other jobs I’ve had, and maybe have guest bloggers who have their own conversion stories to share!

ESL Instructor

Pats Victory March

Students and me at the Pats victory march, 2002

Being an ESL instructor trained me to speak and write very simply, without talking down to the person I’m talking to. Actually, I think I always had this skill. I remember several international students in college telling me that I was “good at talking to international students.” I had no idea what they meant until I was one myself, in Paris. Many people, perhaps most, if you do not speak their language fluently, will treat you as if you are unintelligent, or a child. They can’t see that the person across from them is not only an adult with all their wits about them, but possibly more intelligent than they are.

I think this is important for technical communicators, especially those on the more technical end. We want to explain things in very simple terms, without being condescending.

Another skill I developed during my ESL years was editing non-native English writing. One of the main classes I taught was essay writing for the TOEFL exam. I had to correct students’ formal essays and make suggestions for rewrites.

One thing I’ve been hearing from technical writers is how much of their time they spend editing “Indian English” into standard English. So, basically exactly what I was doing. I love that kind of work!

Another thing that teaching ESL really emphasizes is formal, correct grammar. Much class time is devoted to explaining grammar, and that which is not largely spent policing it. As a result, it is difficult for ESL instructors not to become “grammar nazis,” and we are likely to be found barking at a cashier about how her sign should say “10 items or fewer” instead of “10 items or less.”

Not only do we tend to use better grammar, but when we’re not sure, we know where to look. I waffled a bit on whether the title of this series should be “Carrying over skills” or “Carrying skills over.” But because I know that it was a question of separable versus inseparable phrasal verbs, I was able to google it. Turns out “carry over” can be either. (Of course, if you’re dealing with a pronoun, then it needs to be separated. But you knew that intuitively, if you’re a native speaker.)

One thing you might not realize that ESL teachers do is rapidly assimilate and then explain new information. Most of us don’t go into teaching ESL because we are grammar whizzes. We go into it because we are native speakers who want to travel. We don’t start by knowing advanced grammar; we have to learn it as we go. The rule I was taught in my TEFL certificate program was, “Always make sure to read one chapter ahead in the textbook.” That’s it. Be just a little bit more informed on the technical aspects, and use your native ear to take care of the rest.

Sound familiar? Technical writers can’t be experts on everything we write about. We have to learn as we go, and learn just enough to understand and explain to a lay audience. Beyond that, our writing skills take the lead.

Well, I could probably think of a few more points, but I think this is enough to give you an idea.

Man, after writing this, I kind of miss teaching ESL! Wonder if I should look for a part-time gig…

Have you transferred to technical writing from another career? Would you like to write a guest post on what skills you carried over? Leave a comment!

Survey results REVISED!

Posted: January 6, 2012 in Technical Writing
Tags:

The main criticism I’ve received of my technical writer survey, and my paper “What non-writing skills are technical communicators using?” is that the sample size is too small. By the time I had to write the paper, I only had nineteen responses. While the thoughtful advice given in the comments sections was very helpful, the statistics themselves were considered untrustworthy by my colleagues and instructor.

Fortunately for us, I never got around to “closing” my online survey, and people continued to take it long after the paper was turned in. As a result, I have thirty-eight responses. Still not definitive, but a doubling of the original sample can’t be scoffed at.

For our collective education, I’ve compiled the results into revised graphs. This not only gives us a larger sample size from which to learn, but allows us to compare with the original graphs to see if the two sample sizes produced much different results.

The first graph was “Tools and techniques used by technical communicators.” Behold the revised edition!

And now let’s see that original graph, with the nineteen responses:

Tools and techniques used by Technical Communicators graph

Aside from the original graph being smaller for some reason, not a bad comparison, huh? The numbers are fortuitously easy to crunch, since the sample size was exactly doubled. With a couple minor exceptions, the results of the revised graph are pretty close to double the results of the original.

Now let’s examine the revised results of the second graph, “Methods of learning.”

And the original?

It’s not an exact doubling, but the pattern is clear.

So was the original sample size large enough after all? Or did we just get lucky? Or are we still too small to have a good idea of what’s going on out there?

And an even more interesting question: Do I close the survey down, or leave it up for further input? I decided to edit it to explain that the paper has already been turned in and graded, but that further responses are welcome for our studies here. Care to add your input?

Looking forward to seeing where this takes us!