% Comments on Writing in Senior Project % H. Conrad Cunningham % 2 April 2019; Revised 15 April 2019 Note: After grading the Initial Design Specification documents in the Spring 2019 offering of Senior Project, I decided to write the following suggestions and comments about the writing. 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 the 40-some papers. These suggestions may help you in producing a better Revised Design Specification and better future documents. The order of the suggestions is not important. 1. 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 suggested what sections you should include in most cases: - Project Overview - User Requirements - Development Environment - Deployment Environment - Architecture - Implementation Strategies - User Interface - Test and Integration Plan - Project Timeline - Bibliography #. 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 work. Do not assume the reader has read your Prospectus or is already familiar with our project. #. Remember that the development environment consists of the set of computer and communications hardware, operating systems, languages, tools, libraries, frameworks, services, etc. that the developer uses 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 configuration for some of these items (e.g., computer memory size, language or tool release number, etc.) #. Recognize that the deployment environment consists of the set of computer and communications hardware, operating systems, languages, tools, libraries, frameworks, services, etc. that the various kinds of "users" need to install and execute 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 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 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 read be read by customers (sponsors) or their representatives (e.g., lawyers, marketers, systems administrators). #. 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. 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 with 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". Another pet peeve: The work "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 for 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, "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. #. 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.