Update MG and MIS checklists

BlankProjectTemplate/docs/Design/MG/MG-Checklist.tex

@@ -32,7 +32,7 @@
 
 \begin{itemize}
  
-\item Follows writing checklist
+\item Follows writing checklist (full checklist provided in a separate document)
   \begin{todolist}
   \item \LaTeX{} points
   \item Structure
@@ -41,126 +41,30 @@
   \item Writing style
   \end{todolist}
 
-\item Follows the template, all parts present
+\item Module Decomposition
   \begin{todolist}
-  \item Table of contents
-  \item Pages are numbered
-  \item Revision history included for major revisions
-  \item Sections from template are all present
-  \item Values of auxiliary constants are given (constants are used to improve
-    maintainability and to increase understandability)
+  \item One module one secret (unless an explicit exception is made, with a good
+    reason) - all ``and''s should be checked.
+  \item The uses relation is a hierarchy.
+  \item Secrets are nouns (generally).
+  \item Traceability matrix between modules and requirements shows every
+    requirement is satisfied by at least on module
+  \item Traceability matrix between modules and requirements shows that every
+    module is used to satisfy at least one requirement
+  \item Traceability matrix between likely changes and modules shows a one to
+    one mapping, or, if this is not the case, explains the exceptions to this
+    rule.
+    \item Level 1 of the decomposition by secrets shows: Hardware-Hiding,
+      Behaviour-Hiding and Software Decision Hiding.
+      \item Uses relation is not confused with a data flow chart
   \end{todolist}
 
-\item Overall qualities of documentation
+\item MG quality
   \begin{todolist}
-  \item No statement is repeated at the same level of abstraction (for instance
-    the scope should be more abstract than the assumptions, the goal statements
-    should be more abstract than the requirements, etc.)
-    \item Someone that meets the characteristics of the intended reader could
-    learn what they need to know
-  \item Someone that meets the characteristics of the intended reader could
-    verify all of the statement made in the SRS.  That is, they do not have to
-    trust the SRS authors on any information.
-    \item Terminology, definitions, symbols, TMs and DDs can be given without
-      derivation, except possibly for a source (citation), but all GDs and IMs
-      should be derived/justified.  At least check a representative sample for
-      this criteria.
-    \item SRS is unambiguous.  At least check a representative sample.
-    \item SRS is consistent.  At least check a representative sample.
-    \item SRS is validatable.  At least check a representative sample.
-    \item SRS is abstract.  At least check a representative sample.
-    \item SRS is traceable.  At least check a representative sample.
-    \item Literal symbols (like numbers) do not appear, instead being
-      represented by SYMBOLIC\_CONSTANTS (constants are given in a table in the
-      Appendix)
-\end{todolist}
-
-\item Reference Material
-  \begin{todolist}
-  \item All units introduced are listed (searching the document can help look
-    for other units that may be present, but not listed)
-    \item Units listed are each used at least once (manually searching the
-      document is a quick way to check this)
-    \item The names of units named after people are in lower-case
-    \item All symbols used in the document are listed in the table of symbols
-    \item All symbols listed in the table of symbols are used in the document
-    \item All abbreviations/acronyms used in the document are listed in the
-      table of abbreviations/acronyms      
-    \item All abbreviations/acronyms listed in the table of
-      abbreviations/acronyms are used in the document
-    \end{todolist}
-
-\item Introduction
-  \begin{todolist}
-  \item Introductory blurb focuses on the problem domain
-  \item Introductory blurb Includes a ``roadmap''
-  \item ``Purpose of the Document'' discusses the documentation's purpose, not
-    the program's purpose
-  \item Scope of the requirements is an abstract version of the assumptions
-  \item Characteristics of the intended reader are not confused with the user
-    characteristics
-  \item Characteristics of the intended reader are unambiguous
-  \end{todolist}
-
-\item General System Description
-  \begin{todolist}
-  \item System context includes a figure showing the relation between the
-    software system and external entities
-  \item User characteristics are unambiguous
-  \item User characteristics are specific
-  \item System constraints have an appropriate rationale (a constraint without a
-    reason for that constraint is likely making the SRS less abstract than it
-    should be)
-  \end{todolist}
-
-\item Problem Description
-  \begin{todolist}
-  \item Each item of the physical system is identified and labelled
-  \item Goal statements are abstract
-  \item Goal statements use a minimal amount of technical language,
-    understandable by non-domain experts 
-  \end{todolist}
-
-\item Solution Characteristics Specification
-  \begin{todolist}
-  \item Each assumption is ``atomic'' (no explicit or implicit ``ands'')
-  \item Assumptions are a refinement of the scope
-  \item Each assumption is referenced at least once
-  \item A link exists between each chunk and anything that references it
-  \item The rationale is given for assumptions that require justification
-  \item The derivation of all GDs as refinements from other models is clear
-  \item The derivation of all IMs as refinements from other models is clear
-  \item All DD are used (referenced) by at least one other model
-  \item The IMs remain abstract
-  \item Input data constraints are given, with a rationale where appropriate
-  \item Properties of a correct solution are given
+  \item Follow template
+  \item Low coupling
+  \item Satisfies information hiding
   \end{todolist}
-  
-\item Functional Requirements
-  \begin{todolist}
-  \item IMs and (possibly) TMs and GMs are referenced as appropriate by the
-    requirements.
-  \item All requirements are validatable
-  \item All requirements are abstract
-    \item Requirements are traceable to where the required details are found in
-      the document
-  \end{todolist}
-
-\item Nonfunctional Requirements
-  \begin{todolist}
-  \item NFRs are verifiable
-  \end{todolist}
-
-\item Likely and Unlikely changes
-  \begin{todolist}
-  \item Likely changes are feasible to hide in the design
-  \end{todolist}
-
-\item Traceability Matrices
-  \begin{todolist}
-  \item Traceability matrix is complete
-  \end{todolist}
-
 \end{itemize}
 
 \end{document}

BlankProjectTemplate/docs/Design/MIS/MIS-Checklist.tex

+\documentclass[12pt]{article}
+
+\usepackage{hyperref}
+\hypersetup{colorlinks=true,
+    linkcolor=blue,
+    citecolor=blue,
+    filecolor=blue,
+    urlcolor=blue,
+    unicode=false}
+\urlstyle{same}
+
+\usepackage{enumitem,amssymb}
+\newlist{todolist}{itemize}{2}
+\setlist[todolist]{label=$\square$}
+\usepackage{pifont}
+\newcommand{\cmark}{\ding{51}}%
+\newcommand{\xmark}{\ding{55}}%
+\newcommand{\done}{\rlap{$\square$}{\raisebox{2pt}{\large\hspace{1pt}\cmark}}%
+\hspace{-2.5pt}}
+\newcommand{\wontfix}{\rlap{$\square$}{\large\hspace{1pt}\xmark}}
+
+\begin{document}
+
+\title{MIS Checklist}
+\author{Spencer Smith}
+\date{\today}
+
+\maketitle
+
+% Show an item is done by   \item[\done] Frame the problem
+% Show an item will not be fixed by   \item[\wontfix] profit
+
+\begin{itemize}
+ 
+\item Follows writing checklist (full checklist provided in a separate document)
+  \begin{todolist}
+  \item \LaTeX{} points
+  \item Structure
+  \item Spelling, grammar, attention to detail
+  \item Avoid low information content phrases
+  \item Writing style
+  \end{todolist}
+
+\item MIS syntax
+  \begin{todolist}
+  \item Exported constants are ``hard-coded'' literal values, not variables.
+    Constants are values that are known at specification (and therefore compile) time
+  \item 
+  \end{todolist}
+
+\item MIS Module Classifications
+  \begin{todolist}
+  \item Types that only hold data (records) are modelled as exported types.  For
+    instance, the StdntAllocTypes module in A2:
+    \url{https://gitlab.cas.mcmaster.ca/smiths/se2aa4_cs2me3/blob/master/Assignments/A2/A2.pdf})
+  \item Types that have data (state) and behaviour are modelled as ADTs.  The
+    MIS should use the keyword \textbf{Template}.  An example is the BoardT ADT
+    given at
+    \url{https://gitlab.cas.mcmaster.ca/smiths/se2aa4_cs2me3/blob/master/Assignments/A3/A3Soln/A3P1_Spec.pdf}
+  \item Abstract objects are used when there is only one instance.  There is
+    state and behaviour.  This most
+    often comes up for ``global'' reader and writer modules.  For instance, a
+    module that does logging.  Abstract objects do NOT use the word Template in
+    the main header.  An example is given in the SALst module of A2:
+    \url{https://gitlab.cas.mcmaster.ca/smiths/se2aa4_cs2me3/blob/master/Assignments/A2/A2.pdf}
+    \item Library modules are used when there is only behaviour, no state.  They
+      are defined as Modules, but State Variables and Environment Variable
+      fields say ``None.''
+  \item If the module's MIS can be parameterized by type, then the keyword
+    \textbf{Generic} is used.  Generic modules are usually also Template
+    modules, but not necessarily.  An example is given in the Generic Stack
+    Module (Stack(T)) given in A3:
+    \url{https://gitlab.cas.mcmaster.ca/smiths/se2aa4_cs2me3/blob/master/Assignments/A3/A3Soln/A3P1_Spec.pdf}
+  \end{todolist}
+  
+\item MIS Semantics for each module
+  \begin{todolist}
+  \item Each access program does something - either an output, or a state
+    transition
+  \item Access programs either change the state of something, or have an output.
+    Only rarely should an access program do both (as it does for the constructor
+    in an ADT.)
+  \item If there is an entry in the state transition, then the state of
+    something changes.  The state change might be the local state variables, the
+    state variables for another module, or an environment variable.
+  \item Outputs use $out := ...$
+  \item Exceptions use $exc := ...$
+        
+  \end{todolist}
+
+  \item Mathematical syntax
+  \begin{todolist}
+    \item Operations do not mix incorrect types.  For instance, a character is
+      not added to an integer, an integer is not ``anded'' with a Boolean, etc.
+    \item Our modified Hoffmann and Strooper notation is used, or any new
+      notation is clearly defined.
+  \end{todolist}
+
+\item MIS Quality inspection for each module
+  \begin{todolist}
+  \item Minimality
+  \item
+  \end{todolist}
+
+\item MIS Completnesss
+  \begin{todolist}
+  \item All types introduced in the spec are defined somewhere
+  \item
+  \end{todolist}
+
+\end{itemize}
+
+\end{document}

BlankProjectTemplate/docs/Writing-Checklist.tex

@@ -73,6 +73,8 @@
   \item Document is spell checked!
   \item Grammar has been checked (review, ask someone else to review (at least a few
     sections)).
+  \item That and which are used correctly
+    (\url{http://www.kentlaw.edu/academics/lrw/grinker/LwtaThat_Versus_Which.htm})
   \item Symbols used outside of a formula should be formatted the same way as
     they are in the equation.  For instance, when listing the variables in an
     equation, you should still use math mode for the symbols.