diff options
Diffstat (limited to 'styleguide.tex')
| -rw-r--r-- | styleguide.tex | 267 |
1 files changed, 267 insertions, 0 deletions
diff --git a/styleguide.tex b/styleguide.tex new file mode 100644 index 0000000..39ecbc7 --- /dev/null +++ b/styleguide.tex @@ -0,0 +1,267 @@ +%% +%% This is file `styleguide.tex', +%% generated with the docstrip utility. +%% +%% The original source files were: +%% +%% 6033dp1.dtx (with options: `styleguide') +%% +%% Copyright (C) 2009 by the Writing Across the Curriculum staff +%% +%% All rights reserved. +%% +\documentclass[strict]{6033dp1} + +\title{Style Specification: A Guide to Formatting \\ + Conventions for the DP1 Report} +\author{Writing Across the Curriculum Staff} +\date{March 13, 2009} + +\usepackage{graphicx} + +\begin{document} +\maketitle + +\section{Introduction and Overview} +Technical documents are judged by how completely, clearly, and quickly +they deliver information to a reader. Skillful use of paragraphing, +sentence structure, and the proper use and definition of technical +terminology will help you create an informative document. Careful +attention to the formatting of the report will improve its readability +and make information easier to find. + +Most organizations that produce professional documents have a style +specification, style sheet, or other document that determines the +overall look of reports and other written material. Although specific +conventions vary, guidelines help to ensure consistent format within a +particular community of writers. The guidelines we use are based on +The Mayfield Handbook of Technical and Scientific Writing + +\url{https://web.mit.edu/course/21/21.guide/www/home.htm} + +For a complete discussion of any topic mentioned in this document, +follow the link to refer to the Mayfield Handbook. + +\subsection{Global Document Format} +The following conventions allow you to give your report a professional +look and make information easy for the reader to find. Writers can +achieve a clear, legible page layout using most generally available +text editing, word processing, or document production programs. + +\begin{itemize} +\item Text should be single-spaced, left-justified (ragged right + margin). Leave one extra line space between paragraphs. +\item Use a single-column layout. +\item Font should be standard, 11- or 12-point. You may use a second + typeface or type style for headings, captions, and other special + text. Use these special effects sparingly. +\end{itemize} + +\subsubsection{Headings} +Headings should stand out clearly from the running text of your +report. \uline{Levels} of headings should be easy to identify; the +reader should easily distinguish high-level information from details +and examples. + +You may indicate levels of headings through the use of type size and +style. For a short document such as the DP1 report, which is limited +to 2500 words, too many levels of headings can be confusing. Use just +\uline{three levels}. + +Table~\ref{headingstyles} gives examples of the formatting styles for +three levels of section headings. + +\begin{table}[!h] + \caption{Heading Levels and Styles} + \label{headingstyles} + \begin{fulltabular}{|X|X|X|} + \hline + \thead{Unnumbered Headings} & \thead{Numbered Headings}\\ + \hline + {\bfseries\Large Main Heading} &% + {\bfseries\Large 1.0 Main Heading}\\ + \hline + {\bfseries\large Second-Level Heading} &% + {\bfseries\large 1.1 Second-Level Heading}\\ + \hline + {\bfseries Third-Level Heading} &% + {\bfseries 1.1.1 Third-Level Heading}\\ + \hline + {\bfseries Another Third-Level Heading} &% + {\bfseries 1.1.2 Another Third-Level Heading}\\ + \hline + \end{fulltabular} +\end{table} + +For more information on headings, see:\\ +\url{https://web.mit.edu/course/21/21.guide/www/headxsh.htm} + +\subsection{Paragraphs and Logical Units of Information} +Readers of technical writing tend to skim documents, read them out of +order, and refer to sections that contain information they +particularly need. Because readers have such a variety of styles of +using a document, they rely on writers to arrange information by topic +and to establish a clear progression of ideas. + +If you craft a paragraph's first sentence carefully, that sentence can +establish context for the rest of the information in the paragraph and +announce the structure for presenting that information. These first +sentences may be referred to as \uline{topic sentences}, +contextualizing statements, or point sentences. Spend extra time on +first sentences, and make sure that paragraphs are unified, focused, +and coherent. + +Use \uline{bulleted and numbered lists} sparingly, and do not use them +to substitute for full discussions or explanations. Lists should be +introduced with a short paragraph that explains and supplies context +for the items in the list. Make sure that the items in the list +belong together and that they are grammatically parallel. + +For example, you might begin each item with a boldface term and one or +more sentences explaining the term. You might also list a series of +complete sentences or phrases that fit together logically. + +For a complete discussion of topic sentences:\\ +\url{https://web.mit.edu/course/21/21.guide/www/topic-s.htm} + +For more information on the role of paragraphs and sentences, see:\\ +\url{https://web.mit.edu/course/21/21.guide/www/paragraf.htm}\\ +\url{https://web.mit.edu/course/21/21.guide/www/sentence.htm} + +For more information on bulleted lists and other units of information, +see:\\ +\url{https://web.mit.edu/course/21/21.guide/www/layout.htm} + +\subsection{Guidelines for Graphics} +If you are not accustomed to using graphics to explain concepts, spend +some time looking at the illustrations in your course readings. Which +graphics are helpful? Which ones are confusing? When students +critique the graphics they find in textbooks, manuals, and published +articles, they often complain that these illustrations are cluttered, +inaccurate, or difficult to relate to the concepts explained in +running text. Give some thought to the specific point being made in +your graphic. Adding captions, annotations, and figure numbers helps +readers to understand the point being made. + +\subsubsection{Integrate graphics and text:} +\begin{itemize} +\item Summarize the intention of the graphic in the body text of your + report. +\item Place the graphic as close as possible to a description of what + it illustrates. +\item Use figure numbers and captions so that readers can switch + attention between text and graphics easily. Captions do count + against your word limit, but readers often pay more attention to + captions than to body text. +\end{itemize} + +\begin{itemize} +\item The figure number and title belong under the figure. You may + put explanatory text after the figure title. + + For example, see the caption of Figure~\ref{samplefigure}. + + \begin{figure}[!h] + \includegraphics[width=4in]{figure1} + \caption{A generic illustration. Note that two unrelated place + names are featured, and the cylinder on the left appears to be + sulking.} + \label{samplefigure} + \end{figure} + +\item In contrast, the table number and title belong \emph{on top of} + the table, and explanatory text does \emph{not} follow the table + title. If necessary, concise explanatory notes may go in small type + flush under the bottom of the table, as shown in + Table~\ref{reportedvalues}. + +\item Refer to visuals by number only, not position. For example, + write ``See Table \ref{reportedvalues}'' not ``See Table + \ref{reportedvalues} \emph{below}.'' + + \begin{table}[!h] + \caption{Reported values for $a^2 + b^2$} + \label{reportedvalues} + \begin{fulltabular}{|X|X|X|} + \hline + $a$ & $b$ & $a^2 + b^2$\\ + \hline + $1$ & $0$ & $1$\\ + \hline + $2$ & $10$ & $103$\footnotemark[1]\\ + \hline + \end{fulltabular} + + \small\footnotemark[1] This value is suspect + \end{table} + +\item Use a separate numbering scheme for tables and figures, as + illustrated by Figure~\ref{samplefigure} and + Table~\ref{reportedvalues}. The next figure would be Figure~2, and + the next table would be Table~III +\end{itemize} + +\subsubsection{Emphasize the important detail:} +\begin{itemize} +\item Structure diagrams so important features are emphasized (e.g., + by position, labels, bold). Avoid distracting lines, pictures, or + special effects. +\item Label the axes of graphs, and specify the units of measurement + you are using. +\end{itemize} + +\subsubsection{Using Pseudocode} +You may use pseudocode examples, if they are kept brief and not used +as a substitute for prose explanations. Remember that readers want to +see pseudocode as an illustration, but they will not want to decipher +a page of code to understand how your design works. Pseudocode should +be formatted as a graphic and explained in the text of the report. +For example, the pseudocode in Figure~\ref{rollercoaster} illustrates +the use of 11-point Courier typeface to set it off from the rest of +the report's text, which is 12-point Times Roman. + +\begin{figure}[!h] +\begin{lstlisting} +if(height > 60) { + cout << "You may ride this rollercoaster"; +} else { + cout << Maybe your older sibling will go with you"; +} +\end{lstlisting} + \caption{Pseudocode for rollercoaster riders.} + \label{rollercoaster} +\end{figure} + +The example in Figure~\ref{emperors} shows additional hypothetical +code. It provides a second illustration of 11-point Courier bold as +contrast with the report's running text: + +\begin{figure}[!h] + \begin{lstlisting} +while(ROME_BURNS) { + fiddle; +} + \end{lstlisting} + \caption{Pseudocode for emperors.} + \label{emperors} +\end{figure} + +For more information on graphics, see:\\ +\url{https://web.mit.edu/course/21/21.guide/www/grfxfig.htm} + +\subsection{Footnotes} +\uline{Do not use footnotes} in the DP1 Report. Consider the word +limit, and then weigh the value of any information you plan to include +against the space you have available. If the information is +important, find a way to incorporate it into the report's running +text. Bear in mind that any text included in footnotes counts against +the 2500-word limit. + +To document your sources, use the IEEE style of in-text citation. For +more information on IEEE citation, see: + +\url{https://web.mit.edu/course/21/21.guide/www/doc-ie3.htm} +\end{document} +\endinput +%% +%% End of file `styleguide.tex'. |