Writing notes on design documents List common mistakes made * General Notes 1. Introduce new terms in italics, not in quotes. Bad: our system is called "foo" Good: out system is called \textit{foo} 2. Images in figures should use scalable graphics (EPS or PDF), not bitmapped graphics. I recommend using the unix tool "xfig". Also make sure figures' fonts are large enough to see. You can span a figure across two columns with a "*" style \begin{figure*} \end{figure*} 3. When listing multiple steps, use an itemized list in latex: % produce a bulleted list \begin{itemize} \item text for first item \item text for second item \item ... \end{itemize} % produce a enumerated list (1, 2, 3, ...) % useful to enumerate if you're listing steps of, say, an alg. \begin{enumerate} \item text for first item \item text for second item \item ... \end{enumerate} 4. Use math mode for math symbols Bad: 10 * N Good: 10 $\mult$ N Good: 10 $\times$ N Use math mode for greater-than symbols (instead of just ">") 5. Reference all figures in the text. Each fig has a \lable{fig-foo}. Then text around figure should say "Figure~\ref{fig-foo} shows the ..." or "See Figure~\ref{fig-foo}". Note: caption under figure should summarize figure, not detail it. 6. Consistent capitalization of special terms. e.g., EXT4, Ext4, and ext4. DMDEDUP, DM-dedup, Dmdedup, etc. 7. Space before open parentheses Bad: ... the data structure we designed(see Figure N). Good: ... the data structure we designed (see Figure N). 8. Avoid using so many parenthetical statements. Best to not have any. Better: ... the data structure we designed. See Figure N. 9. Avoid long sentences. They're hard to understand and parse. Rule in sci. writing: shorter is better. Eg. avoid sentences longer than, say, 10-15 words. Special symbol: "BRK x 2" meaning break this sentence in two (or "BRK x 3") 10. citing figures. Any figures you've copied form the net have to be cited and properly credited (else. plagiarism). Even if you redo figure more cleanly, cite its original source. 11. When to use differnet font styles (a) Italics: new terms: our system is called \textit{dmdedup} (b) Courier ("TeleType", or fixed-width) font for names of functions and filenames. The function \texttt{printf} is found in the file \texttt{/usr/include/stdio.h}. (c) Use small-caps font for names of protocol messages: NFSv4 sends the \textsc{nfs4_null} message. TCP sends an \textsc{ack} message. 12. Any comment I wrote down, should be applied everywhere. Sometimes I'll use the "for-all" math symbol to indicate that this problem should be fixed everywhere. 13. to embed code into paper \begin{verbatim} // code \end{verbatim} There are all sorts of "pretty" modes in latex for specific coding styles. 14. large numbers, use commas Bad: 1000000 Good: 1,000,000 15. capitalization problems Don't capitalize words that don't need to be. I often mark those with "LC" (Lower Case this word/letter) Similarly, some words need to be capped. I often mark those with "UC" (Upper Case this word/letter) 16. Acknowledgements section Ack any contributors (project sponsors, others, open source systems, etc.) 17. Evaluation plan section Many missed an eval plan section. 18. Missing "the" words. Special symbol, a large "T" written where the word "the" is missing. 19. If you HAVE to use quotes, don't use double quotes Bad: this is call a "false positive" Good: this is call a ``false positive'' 20. Passive voice vs. active voice Passive voice is longer, verbose, and harder to understand. E.g., "Performance benchmarking will be run on the system." Better use active voice, which is clearer and more assertive. E.g., "We will benchmark our system using ..." Special symbol next to passive sentences, "MKA" (Make Active) 21. Space before after comma. Bad: ".. in metadata , and then ..." Bad: ".. in metadata ,and then ..." Good: ".. in metadata, and then ..." 22. Awkward writing When I can't figure out what you're saying at all. Rewrite. Special symbol: "AWK"