% Options for packages loaded elsewhere
\PassOptionsToPackage{unicode}{hyperref}
\PassOptionsToPackage{hyphens}{url}
%
\documentclass[
]{article}
\usepackage{lmodern}
\usepackage{amssymb,amsmath}
\usepackage{ifxetex,ifluatex}
\ifnum 0\ifxetex 1\fi\ifluatex 1\fi=0 % if pdftex
  \usepackage[T1]{fontenc}
  \usepackage[utf8]{inputenc}
  \usepackage{textcomp} % provide euro and other symbols
\else % if luatex or xetex
  \usepackage{unicode-math}
  \defaultfontfeatures{Scale=MatchLowercase}
  \defaultfontfeatures[\rmfamily]{Ligatures=TeX,Scale=1}
\fi
% Use upquote if available, for straight quotes in verbatim environments
\IfFileExists{upquote.sty}{\usepackage{upquote}}{}
\IfFileExists{microtype.sty}{% use microtype if available
  \usepackage[]{microtype}
  \UseMicrotypeSet[protrusion]{basicmath} % disable protrusion for tt fonts
}{}
\makeatletter
\@ifundefined{KOMAClassName}{% if non-KOMA class
  \IfFileExists{parskip.sty}{%
    \usepackage{parskip}
  }{% else
    \setlength{\parindent}{0pt}
    \setlength{\parskip}{6pt plus 2pt minus 1pt}}
}{% if KOMA class
  \KOMAoptions{parskip=half}}
\makeatother
\usepackage{xcolor}
\IfFileExists{xurl.sty}{\usepackage{xurl}}{} % add URL line breaks if available
\IfFileExists{bookmark.sty}{\usepackage{bookmark}}{\usepackage{hyperref}}
\hypersetup{
  pdftitle={Comments on Writing in Senior Project},
  pdfauthor={H. Conrad Cunningham},
  hidelinks,
  pdfcreator={LaTeX via pandoc}}
\urlstyle{same} % disable monospaced font for URLs
\setlength{\emergencystretch}{3em} % prevent overfull lines
\providecommand{\tightlist}{%
  \setlength{\itemsep}{0pt}\setlength{\parskip}{0pt}}
\setcounter{secnumdepth}{-\maxdimen} % remove section numbering
\usepackage{caption}
\DeclareCaptionLabelFormat{nolabel}{}
\captionsetup{labelformat=nolabel}

\title{Comments on Writing in Senior Project}
\author{H. Conrad Cunningham}
\date{2 April 2019; Revised 15 April 2019}

\begin{document}
\maketitle

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.

\begin{enumerate}
\def\labelenumi{\arabic{enumi}.}
\item
  Use the spelling- and grammar-checking features of your word
  processing tools.
\item
  Proofread the paper manually. Read it aloud to yourself. If it does
  not read smoothly, then it is likely not well written.
\item
  Watch out for homonyms---words that sound alike. For example, consider
  ``to'', ``too'', and ``two'' or ``fourth'' and ``forth''.
\item
  Include a cover page.
\item
  Use appropriate section titles.

  The assignment description suggested what sections you should include
  in most cases:

  \begin{itemize}
  \tightlist
  \item
    Project Overview
  \item
    User Requirements
  \item
    Development Environment
  \item
    Deployment Environment
  \item
    Architecture
  \item
    Implementation Strategies
  \item
    User Interface
  \item
    Test and Integration Plan
  \item
    Project Timeline
  \item
    Bibliography
  \end{itemize}
\item
  Include a description of the Minimum Viable Product, either as a
  separate section or a subsection of some other section such as User
  Requirements.
\item
  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.)
\item
  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.
\item
  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.)
\item
  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.
\item
  Include details such as overall software structure and information
  structure (e.g.~database design) in the Architecture section.
\item
  Engage your brain before starting your fingers typing.
\item
  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).
\item
  Stay factual. Avoid hype.
\item
  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.
\item
  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).
\item
  Write complete sentences in most cases. Unless you are a quite skilled
  writer, avoid use of sentence fragments.
\item
  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.
\item
  Avoid overuse of passive sentences.

  Passive -- ``The exception was thrown by the Java method.''

  Active -- ``The Java method threw the exception.''
\item
  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.
\item
  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.
\item
  Use figures with images, diagrams, tables, etc. to convey information.
  In many cases, you should give a caption and a Figure number.
\item
  Make sure that the contents of a figure are legible when viewed on a
  monitor and when printed on paper.
\item
  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.
\item
  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.
\item
  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.
\item
  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.
\item
  Avoid unnecessary technical jargon.
\item
  Define most acronyms on first occurrence.
\item
  Avoid verbosity, unnecessary redundancy, and excessive hedging.
\item
  Consider making your document accessible to persons with disabilities.
\item
  Remove excessive excrement from your paper.
\item
  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.
\end{enumerate}

\end{document}