Author Guidelines

Introduction

This page provides guidelines for authors creating or editing Demonstrations. The Participate page has all the information you need to make a Demonstration—this page gives tips that authors have found useful.

Before You Start

Search through the existing Demonstrations for topics close to yours. Some topics in the site, like trigonometric functions, are very densely populated, so vary your search terms to make sure you see everything relevant. It is fine if there is already something similar to your idea—just give your Demonstration a different emphasis.

  • Avoid copying cells from other notebooks. These can corrupt the Authoring notebook. It's fine to copy cell contents.
  • Add the searched keywords and phrases to the Related Links section, with one keyphrase per cell.
  • In Related Links, put the titles of related Demonstrations, one per cell. Just the title, and nothing else. For each, select the title, and use Insert Hyperlink to add a link to the related Demonstration.
  • Download and look at other Authoring notebooks to see samples for how they are structured.

Demonstration Title

  • Make the title as specific as you can. "Density Map for the 3n + 1 Problem" is a better title than "3n + 1 Problem."
  • The Demonstration's title and file name are generated from what you enter in this section, so the file name of the notebook you upload does not matter.
  • The permanent URL of a Demonstration is also generated from the title. We encourage authors to use standard English alphanumeric characters, because the URL syntax does not support many characters from outside this set.
  • The Title Should be in Title Case, with All Major Words Capitalized.

Coding Your Manipulate

  • Make all control labels in the output as descriptive as possible, with only proper nouns and proper adjectives capitalized.
  • Choose your controls judiciously. Unnecessary clutter only distracts from the idea of your Demonstration.
  • Let the sliders do the animating. A slider that steps through an evolution is usually better than an animation the user cannot control.
  • Label controls clearly with English words: "number of subdivisions n" is more instructive than "n."
  • InputField is not supported in Demonstrations.
  • Set Appearance->"Labeled" for any slider whose values should be displayed to the right of the slider. Display other useful data in the content area of the Manipulate, for instance as a PlotLabel.
  • Nested Manipulates or functions that return Manipulate are not allowed. Keep things simple and use only one Manipulate per Demonstration.
  • Appearance->"Open" is not allowed for Manipulate controls in Demonstrations, as it takes up precious screen space. Users can open the controls manually.
  • Don't use Format / Face / Italic or Bold for controls or displayed items within the code.
  • For italics, use something like Row[{"iterations ", Style["n", Italic]}]
  • Formulas should only be in the Caption or Details. If still necessary, something like Row[{"formula ", TraditionalForm[(-b \[PlusMinus] Sqrt[b^2 - 4 a c])/(2 a)]}] can be used if the variables in the formula are not used as variables in the code.
  • Display other useful data in the content area of the Manipulate, for instance as a PlotLabel, but do not repeat the title.

Testing Your Demonstration

Check your Demonstration before you upload. This will speed it through our review process.

  • The Demonstration's screen size, including its controls, should not change as controls are manipulated. The outer border of each Demonstration should lie outside the white area of the Test Image Size palette and inside the translucent green area. The palette is located in the Tools menu. Also, consider setting an ImageSize option or using a Pane construct to control the size of your Demonstration.
  • Move each control to its limits. Check for any error messages, unnecessary slowdowns, or other signs of improper function.
  • As you move the controls, check for any jiggling of the Manipulate contents. You can eliminate jiggling by using the PlotRange or ImagePadding options, Spacers, or a Pane construct.
  • If the number at the end of a slider changes in length, it can push the result of the Manipulate on its right. To avoid that, set the iteration number for the control to 0.001 or the like, for example {x,0,1,.001}.

Caption and Details

Review and edit the Caption and Details sections to make them as clear as possible.

  • In the Caption, give a brief description of what the Demonstration shows.
  • At the end of Details, add a single cell with the word References, if you used any (Reference for one). Follow with a list of references, one per cell, numbered, in brackets: [1], [2]. If part of your Caption or Details is based on reference 2, then add [2] at the end of the pertinent sentence. The references should be in numerical order in the caption. Try to follow the reference style shown in the notebook template as best you can, and give all the information you have available about the sources you are using, including a web page URL if possible. Our editors will check the references and edit them further in accordance with our style.
  • There is no need to explain a subtopic at length if the references do so.
  • Define all variables that are visible in the Manipulate panel.
  • To format a single variable in text, select it and press Ctrl-9. To type a formula or equation, start with Ctrl-9, type, and end with Ctrl-0.
  • The front end automatically adds visual spacing to math, so do not type spaces except for multiplication. To close spaces after an operator (e.g. like the difference operator capital delta), use an invisible space: esc-space-esc
  • To move text from one section to another, copy the contents of cells, not the cells, because they carry information with them about the section.
  • Avoid double spaces after punctuation.

Troubleshooting

Authoring Information

The first line should always be "Contributed by: [author's name]".
Possible additional lines include:

  • "Based on a program by:..." if code from another program was used.
  • "Suggested by:..." if someone suggested the idea to the author.
  • "After work by:..." if the Demonstration builds on a book, paper, etc.
  • "With additional contributions by:..." if the primary author received significant assistance.

Final Checks

Go through the following checklist to avoid most of the common errors.

  • Spell check (Edit / Check Spelling).
  • From the top of the Authoring notebook, Tools / Test Image Size, and make sure the Manipulate panel fits.
  • In Thumbnail, there should be a single Manipulate panel. Make sure the sliders work.
  • In Snapshots, there should be three or more different Manipulate panels in separate cells. Make sure the sliders work.
  • Make sure the Manipulate panels are the same size, that they don't change size as sliders are moved, and that they don't change other Manipulate panels.
  • From the top of the Authoring notebook, use Update Thumbnail and Snapshots; make sure the number of items updated matches the total of Manipulate, Thumbnail, and Snapshots.
  • Close Mathematica. Relaunch the notebook. If there are errors, panel resizing, or cell brackets not resolving, fix the problems.
  • From the + in the upper-right corner of a Manipulate panel, run Autorun. Watch for resizing issues or errors.
  • If Autorun takes a long time to resolve, add AutorunSequencing to limit the controls. If any controls are set to ControlType -> None, use AutorunSequencing to prevent Autorun from trying to activate them.