Style Guide
The purpose of this page is to provide some general guidelines for use while creating our document. As a professional project we want the final product to sound uniform and consistent. Our users should not be thinking that six different people were writing this document, instead everything should sound like it is coming from one source. Note: This is a living page. As our team continues to work on the product, material may be added or removed from this page depending on the decisions of the whole group.
Pattern of Exposition
- When writing procedures and tutorials the following pattern of exposition is recommended.
- Give the command for a step
- Describe how the program will respond
- Illustrate what happens
- Tell what the next step is
Titling
- Titles should be written for task orientation. Instead of This is How to Rotate an Image simply title Rotating an Image
- Begin titles with verbs that decribe the actions that are going to be taken. Examples: Merging Layers, Rotating an Image
Tone
- Based upon our audience analysis tone should be casual and personable.
- Write to help, not to condescend. The user is coming to our help system to learn how to use a program and will not want to be treated like a child. Be conscious in writing about how to address the audience without insulting their intelligence.
- Try to keep it simple. Do not over tell how to do something.
Consistency of Language
- To make our document sound unified our language must be consistent.
- Spelling and grammer must be highly maintained.
- Avoid adverb usage as much as possible.
- Working with a computer program means that there is specific language that should be used in describing specific functions or actions.
- Be familiar with the language and use it when appropriate.
- Commonly Used Terms
Tools, Commands, Menu Items, and Hotkeys
- When writing the name of any tools, commands, menu items, or hotkeys remember to bold. Do not just write Crop, write Crop. This will draw the user's eyes to the important terms that tell what tools or commands they are going to use while doing a procedure or tutorial.
- For menu items. If you are writing to a user to explain drop down menu items use --> (arrows) to describe which menu leads to the next. --> should also be bold. Ex. Image --> Resize --> Canvas Size.
For hotkeys use a + sign to link the two (or more) keys pressed. Capitalize all letters when writing a specific hot key. Do not write Ctrl+c instead write it CTRL+C. Note: Do not include spaces between CTRL and + and the letter. Here is a list of Hotkeys Hotkeys for Adobe Photoshop Elements.doc
What is what?
- Suite: A suite is a collection of tutorials that lead the user to a finished product.
- Tutorial: Found within a suite, a tutorial is a personalable way of teaching a user how to use specific tools and operations. Tutorials rely on specific examples and guide the user in every step so that the users end product is the same as the one that the tutorial proposes. For an example look at Group Tutorial.
- Procedure: A straight forward and simple explanation on how to do something. Unlike a tutorial the procedure is more concerned with getting the basic steps on an operation across than it is with producing an actual product at the end. Procedures are fitted for more advanced users in general.
Overviews
- Overviews are just as they sound. They appear at the beginning of a suite or tutorial.
- Overviews will appear in two locations.
- Suite Overviews: This overview will appear at the beginning of a suite and describe what is going to happen in the whole suite and give a general idea why the suite is important.
- Tutorial Overview: This overview will appear at the beginning of every tutorial and, like the suite overview, give some basic information on the material that the tutorial presents and why learning such skills are important. Also in a tutorial overview provide an estimate of how much time the given tutorial should take a user to complete.
The following is an example from our first group tutorial
1. We will again use the 'banjo's image for this tutorial, so go ahead and open it in PE.
2. First, let's rotate the image so the banjoes are pointing upward.
Notice the casual tone of voice and the general simplicity of the sentences. The sample tutorial provides a good idea of the kind of language and tone we are looking for in our document. When confused refer back to it.
Images
- Images like writing should be standardized and consistent.
- Screen shots should be in classic windows theme.
- For now Image Resolution should aim to be within the 75 to 100 pixels/inch.
- Images should probably be no wider than 300 pixels.
Naming Conventions
As we work on this document we will need to save many files of drafts and images. To keep all these files organized and easily accessible we will use a basic naming convention for titling all files. The basic idea of this naming convention is based on what the file is of (Suite, tutorial, procedure, or picture) and the numbered order that the content of the file would appear in on our final product (is it the first suite or the third).
- To begin with we will classify files with the following letters
- s = Suite
- t = Tutorial
- p = Procedure
- i = Image
- _b = body page
- After each letter will be a number so as to indicate the number of apperance on our document. If the file we are saving is for Suite three we would name it s3
- Remember hierarchy. In naming, s for suites should always appear before t for tutorial because a tutorial appears within a suite. This is wrong t4s2 the correct way to title it would be s2t4. The same goes for images. Images always appear within a procedure or tutorial so instead of being named i5p1 or i7t3s2 we would call them p1i5 and s2t3i7.
- Last of all add a one word quick reference to what is in the file. Use an _ to seperate this word from the rest of the file. For example, if your file is for a tutorial on rotating an image in suite number one, name the file something like this s1t3_rotate_b This short end tag will help us know a little more about what the file contains.
Note: Only the author of a file may make changes directly to the file. The files will be available for everyone in the group to read but if you did not write do not make recomendations or changes directly in the file. Instead, copy the file, or print it out, make the desired changes, and get them to the original author to make the final changes to the file.
Some New Stuff to Consider: Choose, Select, Pick, and Click
We need to decide when it is appropriate to use these words. Here is what I am thinking.
- Choose: You "Choose" a tool such as the Crop Tool or other tools from the tool bars.
- Select: The word "Select" should only be used when refering to an action with a selection tool, such as the Magic Wand or the Magnetic Lasso
- Pick: You "Pick" a color
- Click: Use the word "Click" to describe the action of clicking on a button like an OK button in a dialog box.
If there are any questions or disagreement on when to use these words then let's talk about them.
Comments (0)
You don't have permission to comment on this page.