2 April 2019; Revised 3 April 2019
I completed my evaluation of the Initial Design Specification documents. I planned to send each student a scanned copy of his or her document today (Tuesday). But the document feeder on the copier/scanner started jamming. I will send the documents when the feeder is functioning correctly.
My wife (Diana) made a pass over the papers checking grammar, sentence structure, and readability. I followed that with my primary emphasis on content and document structure. Diana’s comments are written in pencil and are neat; mine are in red or green ink are are sloppier.
Some of your papers are quite well written. These use relatively clear, professional English with appropriate content and an effective structure.
Others are not well written. These do not exhibit the level of professionalism that employers expect of Ole Miss CIS graduates.
Everyone can improve. English writing is a skill that we can all learn. Communication is a skill that is essential to success in the profession of computing.
Here are a few suggestions based on my observations of 40-some papers. These suggestions may help you in producing a better Revised Design Specification (due next Monday) and better future documents. The order of the suggestions is not important.
Use the spelling- and grammar-checking features of your word processing tools.
Proofread the paper manually. Read it aloud to yourself. If it does not read smoothly, then it is likely not well written. Watch out for homonyms—words that sound alike. For example, consider “to”, “too”, and “two” or “fourth” and “forth”.
Include a cover page.
Use appropriate section titles.
The assignment description suggests what sections you should include in most cases:
Include a description of the Minimum Viable Product, either as a separate section or a subsection of some other section such as User Requirements.
Ensure that the paper makes sense even if all the section titles are removed. That is, you should have appropriate text that transitions into and out of each section. (The Bibliography is an exception to this. The Project Timeline might be as well.)
Make the Project Overview a relatively short, high-level description of the project. Leave the details to later sections. Be sure to establish the context of your project. Do not assume the reader has read your Prospectus or is already familiar with our project.
Remember that the development environment consists of the collection of computer and communications hardware, special devices, operating systems, programming languages, tools, libraries, frameworks, services, etc. that the developer will likely use (or has used) to design, implement, test, document, maintain, and manage a project and the products and services it provides (including web, mobile, desktop, and embedded apps). It may include specific configurations for some of these items (e.g., computer memory size, language or tool version numbers, etc.)
Recognize that the deployment environment consists of the collection of computer and communications hardware, special devices, operating systems, programming languages, tools, libraries, frameworks, services, etc. that the various kinds of “users” need to install, execute, and administer the project’s products and services.
Although in some cases the development and deployment environments may be similar, they are seldom exactly the same.
Include details such as overall software structure, control flow, and information structure (e.g. database design) in the Architecture section.
Engage your brain before starting your fingers typing.
Identify the target audiences for any document and write so that those audiences can understand what is written and the document answers the questions audience members are likely to have about the project.
A design specification is written for the analysts, developers, testers, documenters, managers, and future maintainers of the project. In some cases, it may be read by customers (e.g., sponsors) or their representatives (e.g., procurement specialists, lawyers, marketers, systems administrators).
In Senior Project, your instructors, other faculty members, your fellow students, and your sponsors form the primary audiences of the documents you write.
Stay factual. Avoid hype.
Cite in the text all the sources (books, papers, websites) of all text or diagrams that your paper quotes, paraphrases, adapts, or uses in some significant way. Include these references in your Bibliography in a standard form. Make sure bibliographic entries are complete and correct.
Write moderate length, coherent, and cohesive paragraphs.
A good question to ask about any paragraph is what is the topic (e.g. topic sentence) of the paragraph. If the paragraph does not have one or has more than one, then it may not be a good paragraph.
I personally prefer short paragraphs for a document that will be read from a digital display (e.g. website).
Write complete sentences in most cases. Unless you are a quite skilled writer, avoid use of sentence fragments.
Avoid excessive use of overly complex, run-on sentences. There is nothing wrong with writing mostly short declarative sentences.
However, make sure your writing is not overly choppy by writing sentences of varying length and complexity.
Avoid overuse of passive sentences.
Passive — “The exception was thrown by the Java method.”
Active — “The Java method threw the exception.”
Use the structured (e.g., bulleted or numbered) list feature of your word processor judiciously.
Some of the papers underused this feature. These may have relatively long lists of similar items that are embedded in sentences inside paragraphs. These “lists” would be easier to comprehend if presented using a list feature.
Some papers overused this feature. A section that is nothing but a collections of bullets, is inappropriate. Write appropriate text to introduce a list, letting the reader know what is in the list.
Construct each list with a parallel structure. For example, begin all items in a list with a verb in the same tense/form, a noun, etc. Make all phrases or sentences. (If you have additional information, use full sentences.)
Note that items in the numbered list I use in this document all begin with active, present tense verbs. All are full imperative sentences withe the implied subject “you”.
Use figures with images, diagrams, tables, etc. to convey information. In many cases, you should give a caption and a Figure number.
Make sure that the contents of a figure are legible when viewed on a monitor and when printed on paper.
Always refer to a figure in the narrative text of the document. Explain what the figure is meant to convey to the reader.
Note that I deviated from the parallel list structure slightly here. I qualified the verb with an adverb to emphasize the importance of the point.
Ensure that subjects and verbs agree in number.
Pet peeve: The word “data” is plural. (It is borrowed from Latin.) The singular form is “datum”. So we should say “data are” not “data is”. If I am checking how something reads, I replace “data” by “datums” to see if the sentence sounds correct.
Another pet peeve: The word “faculty” is a singular, collective noun referring to the group of teachers at a school. Some writers tend to misuse it as a plural noun.
Ensure that pronouns agree with their antecedent.
Pet peeve: In informal speaking and writing, the third-person plural pronoun “they” is often used as both singular and plural to avoid use of gender-specific singular pronouns “he” and “she”. (Historically, “he” has been used for both the male and neutral cases.) Personally I prefer to reword the sentence—either to make the antecedent noun plural or to avoid the pronoun altogether.
Similarly, the word “they” is used to refer to an organization. In most cases, we should use “it” to refer to the organization.
Write somewhat formally and professionally in the Senior Project documents, but, of course, try to be interesting. Although sometimes a bit of informality can lighten a dry topic, but too much informality is annoyingly unprofessional.
Avoid unnecessary technical jargon.
Define most acronyms on first occurrence.
Avoid verbosity, unnecessary redundancy, and excessive hedging.
Consider making your document accessible to persons with disabilities.
Remove excessive excrement from your paper.
(Added a few minutes later) Avoid publishing a document late in the evening.
Despite trying to follow my own advice, I discovered at least one misspelled word, one incorrect word because of a typo, and a missing word in the original version of this document. I later found more problems.
As programmers, we should seek to be as precise in our use of English (or other natural languages) as we are in the use of programming languages.