Checklist for writing helper pages

From Math Images

Jump to: navigation, search

This page provides a checklist of attributes of a good helper page.


Is this just a helper page?

First thing's first!

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

Quality of prose and page structuring

  • The beginning paragraph(s) of the page clearly define 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
  • If the page includes a less advanced treatment and a more advanced treatment of the same topic, the less advanced treatment is placed first, and it's clearly stated that the more advanced treatment is just that.


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.

Links to other pages

  • The helper page lists and links to all of the pages that link to it

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).

  • Wherever it makes sense, description of ways in which the content of the page is useful in larger problems are included.

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 in short paragraphs, and broken up by relevant images throughout. What do you think about the "broken up by relevant images" thing for this?
  • 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 a 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