Skip to content

Latest commit

 

History

History
93 lines (71 loc) · 3.71 KB

CONVENTIONS.md

File metadata and controls

93 lines (71 loc) · 3.71 KB

Conventions

This textbook is meant to be:

  • An open educational resource. (CC-BY)
  • Long in its examples, follow-up questions, addressing misconceptions.
  • Short in its definitions.

Legal

Do not plagiarize. Do not misrepresent someone else's work as your own. It is okay to use someone else's material, as long as it is public domain or under a CC-BY or CC-0 license. Any other license, including CC-BY-SA (the license of Wikipedia) is not allowed. Therefore, do not copy from Wikipedia.

Content

Definitions or descriptions are insufficient.

  • Include misconceptions to debunk them. Disclosure: fellow students are a great resource for misconceptions. Professors easily forget what they did not know before. Professors also forget misconceptions they once held.
  • Show, don't tell. Figures, diagrams or examples trump definitions or explanations.
  • Ask and answer questions. Include followup questions.

Writing style

Human-human communication can be more challenging than human-machine communication. Therefore, writing well is just as important as programming well.

  • One sentence per line, please.
  • Keep sentences short. Don't repeat yourself.
  • Choose words wisely. Avoid weasel words or filler phrases. Examples: "the process of", "considered to be"
  • Work together. Ask others to review contributions. Does the writing make sense?
  • Follow these criteria.
  • Follow Strunk & White. Elements of Style.
  • Check spelling, grammar, and punctuation.
  • Use active voice, not passive voice. Active: the professor wrote this document. Passive: this document was written by the professor.
  • Use the appropriate tense. By default, use the present tense.
  • Use the first (we, us) or third (he, she, it, they) person. Do not say "you" unless absolutely necessary (e.g., in conversations).

Images

Save all images into the images folder with a sensible name.

Images come in several formats, of which only three we will use: SVG, JPG, PNG. The type of image determines which format is best.

Diagrams

Diagrams include line drawings, charts, and most figures. Use Scalable Vector Graphics format for diagrams. DO NOT use: ASCII art, PNG or JPG formats.

Software to use

All of these support SVG. Feel free to save diagrams to your working directory, but only commit SVG, not vsd, dia, or odg. Add only SVG to version control.

  • Visio
  • Dia
  • Inkscape
  • LibreOffice Draw

Style

  • Use Arial 10pt for text.

Sizing

In general, save images using US units. Images should be 6 inches (15.24 cm) wide by 4 inches (10.16) tall.

Use images/blank-figure.svg as a starting template. Otherwise,

  • In Visio, hold down CTRL, click and drag on a page corner. Line up against the ruler.
  • In LibreOffice Draw, go to Format -> Page... Ender the width and height.
  • In Dia, go to File -> Page Setup For Paper Size, Select EuroPostcard. Select Landscape.

Photographs

Photographs include anything sourced from a digital camera. Use JPG for photographs. DO NOT use PNG.

Screenshots

For screenshots, use PNG. DO NOT use JPG.

Videos

For screencasts, use screencasting software. For all other videos, use a digital video camera.