Use Context
Content Components
Look and Feel
Sample Pages
Use Context
It walks readers through a tool by following a real-life use case.
Content Components
| Purpose | Style | Sample text | |
|---|---|---|---|
title | quickly identifies the page as a sample project. | name of tool + walkthrough | WordPress Walkthrough |
end result | describes the final project and the content it will contain. | The end result is a longer sentence fragment, general a noun. Title this section "End Result:". | End Result:
An e-portfolio with an “About” page and a CV.
|
requirements | lists the elements the user should have before starting the project. | Use an unordered list. Title this section "Requirements:" |
Requirements: • A CV in pdf form • A WordPress site
|
directions |
lists the broad steps needed to accomplish the project. Each direction will usually be the title of a pre-existing step-by-step guide.
|
Use an ordered list and follow step-by-step guide requirements. Include links to step-by-step guides as sub-directions.
|
1. Open your WordPress site
|
Look and Feel
paragraph: use the default Paragraph format in the editor
headings: use the default Paragraph format and bold in the editor
End Result:
Requirements:
Steps:
expandable steps: place directions as the title of the Expand macro container
1.
imported step-by-step guide: place guide inside the Expand macro, use the Include Page macro: "Page to Include" should be the name of the page you want to import
1.
Layout
Sample Pages
Voice and Tone Tips
Some of these are in the Voice and Tone guide, but we repeat them here. Writing style is especially important, since tutorials are a first point of access into the tool.
Be casual. Make sure your content passes the “email test.”
Be clear and direct.
Avoid sounding cheesy and formal.
Use the bottom line up front approach:
- Don’t write: “This is a real-life assignment that John Alexander, associate director of SHANTI, uses to facilitate reading and discussion in his classroom.”
- Write instead: “John Alexander uses NowComment so that his students can upload and peer review drafts of their final papers.” And then transition to the tutorial.