Author Guidelines
Before You Start
|
Demonstration Title
|
Controls for Your Manipulate
|
Testing Your Demonstration
Caption and Details
|
Troubleshooting
|
Authoring Information
|
Final-Checks
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.
Create a Demonstration for the Wolfram Demonstrations Project »
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.
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 alpha numeric characters, because the URL syntax does not support many characters from outside this set.
Controls for 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" 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 theManipulate
, for instance as aPlotLabel
. - Nested instances of Manipulate or functions that return Manipulate are not allowed. Keep things simple and use only one Manipulate per Demonstration.
- Appearance->"Open" is not allowed for Manipulator 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 aPane
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 thePlotRange
orImagePadding
options,Spacers
, or aPane
construct. - Review and edit the Caption and Details sections to make them as clear as possible.
- Use the Check Spelling button in the Tools menu.
Troubleshooting
- If controls update other panels, there are likely non-localized variables. Try
Module
. - If Update Thumbnails causes strange errors, select the cell with code and try Format / Clear Formatting.
- If your code uses the Initialization section, make sure you've used
SaveDefinitions->True
. - If your initialization is time-intensive, use
SynchronousInitialization->False
. - For time-intensive code like
NDSolve
orFindRoot
, useSynchronousUpdating->False
. - If a Slider is difficult to move due to time-intensive code, try
ContinuousAction->False
. - If panels resize, use a two-part size specification like
ImageSize->{100,100}
. - For
Graphics3D
items, useSphericalRegion->True
. - If errors persist, try using
Quiet
. - If a Slider turns red and stays red, use an
If
statement within the code to set the slider to an allowable value.
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 toControlType -> None
, useAutorunSequencing
to prevent Autorun from trying to activate them.