% Options for packages loaded elsewhere
\PassOptionsToPackage{unicode=true}{hyperref}
\PassOptionsToPackage{hyphens}{url}
%
\documentclass[
  english,
]{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} % provides euro and other symbols
\else % if luatex or xelatex
  \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 Inspired by Grading the Initial Design Specification},
  pdfauthor={H. Conrad Cunningham},
  hidelinks,
}
\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
% Redefines (sub)paragraphs to behave more like sections
\ifx\paragraph\undefined\else
  \let\oldparagraph\paragraph
  \renewcommand{\paragraph}[1]{\oldparagraph{#1}\mbox{}}
\fi
\ifx\subparagraph\undefined\else
  \let\oldsubparagraph\subparagraph
  \renewcommand{\subparagraph}[1]{\oldsubparagraph{#1}\mbox{}}
\fi

% Set default figure placement to htbp
\makeatletter
\def\fps@figure{htbp}
\makeatother

\usepackage{caption}
\DeclareCaptionLabelFormat{nolabel}{}
\captionsetup{labelformat=nolabel}
\ifxetex
  % Load polyglossia as late as possible: uses bidi with RTL langages (e.g. Hebrew, Arabic)
  \usepackage{polyglossia}
  \setmainlanguage[]{english}
\else
  \usepackage[shorthands=off,main=english]{babel}
\fi

\title{Comments Inspired by Grading\\
the Initial Design Specification}
\author{\textbf{H. Conrad Cunningham}}
\date{\textbf{2 April 2019; Revised 3 April 2019}}

\begin{document}
\maketitle

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.

\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. 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 suggests 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 project. 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 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.)
\item
  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.
\item
  Include details such as overall software structure, control flow, 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 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.
\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.

  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).
\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
  withe the 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.

  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''. 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.
\item
  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.
\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
  (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.
\end{enumerate}

\end{document}