Checklist for writing pages

From Math Images

Jump to: navigation, search

This page provides a checklist of attributes of any good image page. It is useful as a reference while working on pages. It is also worth going through the checklist item by item before stopping work on a page or taking an extended break.

Contents

Messages to the Future

  • Suggestions of material for future generations to add, when appropriate.
  • If you have other thoughts about a page you've written that future contributors might find valuable, make a note of them.

References and footnotes

  • All images must be cited on the page you see when you click on it.
  • If you did not create the image, and the source doesn't explicitly state that it's okay to use it, you must email the copyright holder and ask for permission to use the image.
  • Free-to-use images (such as most images found on Wikipedia) should be credited with a link back to the source (even if the image is public domain and you technically don't have to - this helps us keep track of images).
  • If you or another Math Images person created the image, you should give the creator's name and link to their user page.
  • Direct quotes from textual sources are cited.
  • References for text are at the end of the page, with option links to the footnotes within the text.
  • The current idea seems to be that mathematical content doesn't need to be cited. However, if you either learned information that's hard to track down with something like a basic Google search, or you've found an especially appealing presentation of some mathematical content, citing your source would be a great public service.

Good writing

The following items are just meant to be reminders. If one of these items needs clarification, or seems like a great idea that you don't know how to implement, see What Makes a Good Math Images Page?.

Context (aka Generating interest aka Who cares?)

  • The page makes clear why the topic and specific mathematical content of the page are useful and/or why we find it interesting or are motivated to study it. The idea is to allow readers to become curious about and interested in the topic, including . A "Why It's Interesting" section can help with this, especially since newbies can really lack context, but the beginning of the page should also engage the reader.

Quality of prose and page structuring

  • The beginning paragraph(s) of the page clearly define(s) the topic or purpose of the page as a whole, and may outline the page or preview conclusions that will be reached later in the page.
  • The purpose of each section is clearly relevant to the purpose of the page as a whole.
  • The purpose and thesis of each section is introduced as close to the beginning of the page as possible.
  • Subsections that may be of use for existing or future pages are made into Helper Pages
  • Within the "More Mathematical Explanation" section, the heaviest math is placed as late as possible within this section. If readers see math they don't understand, they may simply skip the section entirely instead of looking later for material they do understand.

Integration of Images and Text

  • Wherever an image or animation is used to help with an explanation, the reader is explicitly instructed to refer to the image.
  • The text explicitly points out what the reader should observe in a picture.

Connections to Other Mathematical Topics

  • Wherever possible, relationships between the content of this page and of other topics/ideas in mathematics are identified and explicitly described.
  • Wherever it makes sense, the page links to other Math Image pages, though links should not be forced.

Examples, Calculations, Applications, Proofs

  • Whenever a new idea is introduced, numerical examples or calculations illustrating a concept, definition, or argument are provided if they might be helpful.
  • Proofs are included wherever they would be of interest (this probably means anytime you have a statement whose truth is not totally self-evident and which is important to the page as a whole), but ONLY if writer feels comfortable with the proof (otherwise, it is perfectly acceptable to leave a proof for others).
  • Applications of equations, theorems, etc, either to other branches of math or to the world outside of math, are included whenever these applications seem interesting and/or are needed to set a context (see context section, above).

Mathematical Accuracy and Precision of Language

  • The goal is always that all statements, equations, and mathematical terminology are free of errors.
  • Statements are made as precise as they can be without overwhelming the reader with too many words or dense symbols (and are always precise enough to rule out major ambiguity).
  • Any mathematical term that the reader can't be expected to know is defined (err on the side of defining too many terms), either in the body text or via a mouse-over or link to another web resource or a helper page.

Layout

  • Text is presented in short paragraphs and broken up by relevant images throughout.
  • Hide and mouse-over features are used as appropriate to reduce clutter and scariness. Proofs and large masses of equations in particular should be hidden, and terms should often be defined by mouse-over, rather than in text, if the definitions are short and readers may already know them. But if people cannot be expected to know them, then they should be defined in proper mathematical style, that is, the word being defined should be boldfaced to announce that what follows is a definition, not a rough description.
  • To whatever extent possible, pages do not have large, awkward chunks of white space.
  • When text wraps around images, images don't force dramatically different "margins" for consecutive lines of text.
  • No image in one section of a page vertically aligns with the text or heading of a different section.
  • In hidden text, none of the preview text appears as weird computer code (see Wiki Tricks for help on this).
  • The page has been viewed at a few different window sizes to make sure funky things don't happen.
Personal tools