TMSWiki:Designing templates

Naming

Because our site heavily uses templates to ensure consistent and professional formatting, it is important that we choose names for the templates and the templates' inputs that a casual user who doesn't even know what a template is will still intuitively know what they stand for. It may seem trivial, but the naming of templates and their inputs is very important for making casual visitors feel comfortable editing the page. These new editors could become leaders of the wiki, so it is essential that they not be scared away by the wikitext that they see when they start editing.

Because template names and their inputs often appear many times on different pages, it is worthwhile to agonize over their design in much the same way that Steve Jobs so effectively agonized over design at Apple. Seemingly small differences can determine whether the reader just intuitively and easily "gets it," being amazed at how simple and fun it is to edit Wikitext or whether they throw up their hands in disgust and give up.

Upper Camel Case

For both templates and input names, we use what we refer to as "Upper CamelCase" for template names and input names. CamelCase just refers to several words "smooshed" together, WithNoSpacesInBetweenThem, so that the capital letters look like the humps of a camel. "Upper" CamelCase just means that the very first letter is capitalized. This serves as a subtle cue to the reader that these words are very special and must be spelled and capitalized in a very specific manner. It also groups the words in the name so that it is clear that they are a unit, perhaps encouraging the user to copy and paste when adding a new template rather than just typing out their best guess.

Word Choice

When choosing the words for a template name, recall that an editor of a Structured Program page might not know about templates, but they probably first interacted with the program as someone who used the program. Thus, they know that there are many Boxes that contain a prompt for a question to ponder as well as a collection of lines for them to write on. Ideally, when they see the following code, they should be able to guess exactly what it refers to:

{{SEPQuestionToPonderBox
|Prompt=When was the last time you exercised or did another physical activity?
|NumLines=5}}

To give new editors the experience of "just getting it," think hard about which words will make it as clear as possible what the template is for. Don't skimp on words - the shorter a template name is, the more cryptic it will appear.