Journal GrantRobertson's Journal: Grant's Concise GUI Notation System (GCGUINS)
Grant's Concise GUI Notation System (GCGUINS)
Have you ever noticed that many computer books are over two inches thick but, by the time you finish reading them, you could swear there was only about 3/4 of an inch of information in there? This is because all computer books tend to be excessively verbose when describing how to achieve some task. I have seen books take over two pages just to explain how to set a couple of settings in a simple dialog box. Many authors go crazy cutting and pasting hundreds of copies of various almost identical sets of instructions throughout their books. After a while of trying to plow through all this verbosity, hoping to glean a few morsels of actual new information, I often give up in frustration.
As a former network manager and frequent Usenet poster, I found myself doing the same thing. Repeating the same instructions over and over again for fear that the user would not be familiar with the same instructions I had given elsewhere. Even when I was taking notes for myself, I was forced to write out all these instructions and it was hard for me to go back and quickly see what I had meant by what I had written.
So, being the lazy bum that I am, I started using an abbreviated notation for all these instructions. The organizational freak in me soon took over and found a way to standardize those abbreviations into a cohesive system and GCGUINS - it rhymes with penguins - was born. Why something like this has not caught on already is totally beyond me.
Using this notation system, any author - whether writing a book or a simple newsgroup posting - can quickly and easily communicate a series of steps that a user must take in order to perform some operation in standard software dialogs. I realize that there are many operations that cannot be described using this system, especially for graphical programs like CAD or photo editing programs. However, there is still a huge number of tasks that can be described using GCGUINS, even in these types of programs. By using this system, many hours of typing and reading can be saved by everyone involved. We may even save a few trees while we are at it.
Goals:
- Instructions should be able to be typed in plain text so people can use the text of the instructions in any system and so it will translate well when copied between file formats, such as when copying from text to HTML to a Word® document.
- Should be easily understood by regular people with little prior computer experience and absolutely no programming experience.
Syntax:
- Curly-Braces - { } - Wrap around any complete operation.
- All the steps needed to achieve a single goal or neatly combined set of goals will be between one set of curly brackets.
- Put spaces before and after each curly brace to clearly delineate them and to make it more obvious that this is a list of steps rather than just a comment or something.
- Do not try to combine two separate operations within one set of curly braces. While it is appropriate to combine multiple settings changes to achieve one specific goal or to get set up for one particular situation, it is not appropriate to put two entirely separate tasks within one set of braces. For example:
{ Tools / Options ; <Save> ; Save options, [x] Prompt for document properties ; [OK] ; File / Save as... ; File Name: = Name_of_file ; [Save] }
should be split up into:
{ Tools / Options ; <Save> ; Save options, [x] Promt for document properties ; [OK] }
and
{ File / Save as... ; File Name: = Name_of_file ; [Save] }. - You don't want the user to think that they always need to do the first part before doing the second part.
- In fact, it is perfectly OK to break up complicated operations into multiple separate operations if you think it will be easier to understand.
- Menus - / - Separated by slashes
- Many GUI operations start with the selection of menu items. Any use of menus requires the selection of at least two things: the top level menu name in the menu bar and the sub-item in that menu. These will be separated by regular forward slashes. For example:
- { File / Save } tells how to get to the save dialog box.
- { Insert / Pictures / From Files... } tells how to, well, insert pictures from files.
- Any time you see a forward slash separating two words or phrases then you know it is a menu choice. There is no need to clutter things up by prefixing the list with any additional text or symbols except for...
- Context Menus - *:Target Object / menu item / sub-menu item
- The "*" represents how the user "clicks" on the object with a pointer or stylus or what-have-you, in whatever means is used within the operating system to open the context menu. It is a visual metaphor for the action of clicking. It also represents a sort-of wildcard for all the different possible means to open that context menu. It could mean "right-click" in Windows, or "Option-Click" on a Mac. The user is expected to at least know how to get to a context menu. This makes the system compatible with whatever method for getting to the context menu a particular operating system may use.
- The author could replace the asterisk with the specific means used for the operating system they are describing, or they could simply leave the asterisk there and explain to the user that it means opening the context menu for the target object.
- RC = Right-Click
- CC = Control-Click
- AC = Apple-Click (Do they do that? I don't know.)
- OC = Option-Click
- CH = Click-&-Hold
- DC = Double-Click
- The author can use either the words or the abbreviation. The 'C' could be replaced with a 'T' or "Tap" when the user would be using a stylus but this does not seem necessary.
- Many GUI operations start with the selection of menu items. Any use of menus requires the selection of at least two things: the top level menu name in the menu bar and the sub-item in that menu. These will be separated by regular forward slashes. For example:
Open Object - OO:Name_of_Object
- This means to do whatever is necessary within your operating system to "Open" the object, whether that be double-clicking, option-click, click-and-hold, tap-and-hold, or whatever. The user is expected to know how to do this for their operating system. Again, you could replace 'OO' with an abbreviation or name of a specific action but it will be more portable if you don't.
Gestures
- Gestures are a new feature of some operating systems and programs. Once you do the gesture you are sometimes taken to a regular dialog box or wizard.
If the gesture doesn't take you to some additional dialog box then there is no real need to use this notation system to document it. Using { FG:Flick-Left:Album Art } would be more concise than "Do a left flick on the album art." but it would break up the flow of thought. The detraction from the flow of thought would not be worth the small amount of additional concision achieved. - Mouse Gesture - MG:Name_of_gesture:Object_to_gesture_over
- The name of the gesture should be kept simple and, well, concise. Use "Left-Right-Left" rather than "Move the mouse to the left then the right then back to the left again." After all, we are trying to be
- The name of the gesture should be kept simple and, well, concise. Use "Left-Right-Left" rather than "Move the mouse to the left then the right then back to the left again." After all, we are trying to be
- Finger Gesture - FG:Name_of_gesture:Object_to_gesture_over
- Same as mouse gestures but with your finger on a touch screen. Usually, these don't open any dialog boxes so it won't even be necessary to use this notation. It is listed here merely for completeness.
- Yes, I know all the obvious jokes. Get over it.
Semicolons - ; - Separate each step of the operation.
- There should be a space before and after the semicolon so it isn't confused with part of a name or text in the dialog being described. For example:
- { step one ; step two }
- Selecting a menu item is considered one step. For example:
- { Main menu / sub-menu ; <tab to select> ; [button to click] }
Commas - Section Name,
- When a dialog box has multiple named sections it is helpful to name the sections and follow the name with a comma so the user can more easily find the actual dialog item to be modified. If there is more than one level of sub-sections then just separate the list of names with commas.
- { Main menu / sub-menu ; <tab to select> ; Section on that tab, sub-section, [button to click] }
- Comma separated labels don't indicate a specific thing to do, they just help you find the thing that you are supposed to do something with.
Tabs - <Tab Name>
- Many dialogs have tabbed interfaces. This notation indicates which tab the user should be on or switch to.
- Always list the name of the tab even if it is the default one. This way the user can be sure they are where they need to be.
Buttons - [Button Name] - Square brackets
- Square brackets around a word or phrase indicates a button that should be clicked.
- The square brackets are also used for a few other things but there will only be one letter or symbol between them and they will be part of a step with additional words, so it is easy to tell the difference.
Check Boxes - [x] Name or label of checkbox
- [x] = checked
- [ ] = unchecked. (There should be a space between the square brackets.)
- Naturally, more than one can be checked.
- Yes, I know, there could be a conflict with the red "X" close button in Windows. However, that button should be indicated by using [Close] instead of [X]. This is because that is the actual name of the button and so the instructions will still be correct if the look of the button is changed or the user is using the program in a different operating system.
Radio Buttons - Button_list_label: (x) Name of radio button
- (x) = Selected
- ( ) = Not selected (There should be a space between the parentheses.)
- Only one should be selected.
- Radio buttons should always be preceded by the label for the list of buttons, such as:
- In Firefox 2.0.0.6: { Tools / Options... ; <Tabs> ; New pages should be opened in: (x) a new tab ; [OK] }
Fields - Field Name = "What to type"
- The quotes are included in the GCGUINS instruction but the user should not type them into the field.
- { File / Save as... ; File Name: = "Name_of_file" ; [Save] }
- You could leave the colon at the end of the label or ignore it. I don't think your users will notice. The important part is the equal sign.
Drop-Down List boxes - List-box_Name: = Item_to_choose[v]
- Notice that this is almost like filling in a field except the [v] tells you that you can choose from a list.
- No quotes are necessary because the user isn't typing anything. They are just choosing from something that already appears on the screen.
- { File / Save as... ; Save as type: = File Type[v] ; File Name: = Name_of_file ; [Save] }
- This is consistent with the button metaphor because the drop-down-list-button often looks like a button with a "v" on it.
Drop-Down List boxes where you can type in a new list item - List-box_Name: = "New list item to type in"[v]
- The quotes indicate that there is something for the user to type while the [v] reminds them that this interface item is a list box. If they have typed the same thing before it may now be in the list for them to choose.
Some Simple Examples:
Note: these are all taken from Word or MS Windows XP because I am lazy and they happen to be what I have open right now.
{ Tools / Options... ; <View> ; Formatting marks, [x] Optional Hyphens ; [OK] }
- Turns on the display of optional hyphens.
- Notice that there is a semicolon after <View> because clicking the "View" tab is a separate step from checking the "Optional Hyphens" checkbox.
{ *:Desktop / Properties ; <Screen Saver> ; [Power] ; <Hibernate> ; [x] Enable hibernation ; [OK] ; [OK] }
- Turns on hibernation. Notice that you can work through any series of steps very concisely, even if they take the user to multiple different dialogs. And there is no need to name or describe the dialogs as they appear. People don't usually care about that anyway. They just want to know what they are supposed to do. Pure and simple.
- It should also be easier to remember because the reader can see all the steps at the same time within their field of view. It is always easier to remember what you can visualize as a single unit.
Outline format:
If lots of different settings in lots of different tabs or dialogs need to be changed, it is also possible to use an outline format to list all the steps in an organized fashion. Simply list all the steps necessary to get to a certain point as one heading in your outline. Then list each set of related steps as a sub-heading under that one. For instance, if you need the user to open a dialog then set options on a series of tabs, simply put the instructions to get to the dialog on one level, put the tab names on a sub-level, then put the various settings to change as sub-sub-heading under the tabs. If only one or two settings need to be changed on a particular tab then you can list the tab notation and the setting notation on the same line for compactness. But if a lot of settings need to be changed on a tab then list them all on a different line. Dialog section titles can be treated the same way. For example:
- In Word 2003: { Tools / Options... ;
- <View> ;
- Show,
- [ ] Startup Task Pane
- [ ] Smart Tags
- [x] Picture placeholders
- Field Shading = When Selected[v]
- Formatting Marks, [x] All
- <View> ;
- <General> ;
- [x] Confirm conversion at Open
- [Web Options] ;
- <Browsers> ; Options, [x] Allow PNG as a graphics format
- <Pictures> ; Screen size = 640 x 480
- [OK]
- <Browsers> ; Options, [x] Allow PNG as a graphics format
- [x] Confirm conversion at Open
- <Spelling & Grammar> ;
- Spelling, [ ] Check spelling as you type
- Grammar,
- [ ] Check grammar as you type
- [ ] Check grammar with spelling
- Spelling, [ ] Check spelling as you type
- [OK] }
- (Ignore the bullets. That is the only way I could get the outline to show up right on Slashdot.)
- Those who opened up Word and followed along will notice that I did not list section names when there was only one section in a tab. There is no real need to do so because it provides no additional information. However, you can list them if you want to, just for completeness sake.
- Notice that I could have listed all these on one long line - with or without word-wraps - and it would have given the same instructions. However, by listing them in outline format the entire operation is easier to follow. Put things on one line when it makes sense and spread them out when it makes sense. Use your better judgment. Once you have written it out, take another look at it and ask yourself if you would be able to follow it easily if you were a relative novice.
Notes:
- Naturally, once the author has used this notation once or twice to tell the user how to do something relatively simple such as saving a file with a particular name, then the notation should be dropped and the author should simply write, "Save the file as 'filename'." To continue using the notation would just be irritating to most readers.
- Normally you would only list settings for the things that need to be changed. However, sometimes it is necessary to make sure that quite a few settings are exactly how they need to be for some feature to work. In that case, list all the settings that are pertinent to the situation but leave out all the ones that wouldn't make a difference. You don't want to get carried away listing every setting in the entire system just to achieve one simple goal.
- Normally the user will know the program in which they need to do all these steps from the context of the discussion. However, sometimes you might need to make it clear by simply stating "In Program_Name: { steps }."
- Be sure to list all the steps necessary to complete the operation, including clicking all the [OK] and [Save] buttons. But do not list more steps than are necessary to achieve the goal. For instance, it is not necessary to close a task pane every time after performing some task involving that task pane. In fact, you may want to give separate instructions for opening the task pane and performing the task within the task pane. Then, after you are confident that the user knows how to open the task pane, you can simply write, "In the Foo task pane: { do these steps }."
- There is no need to stick extraneous underscore characters between words or put quotes around multi-word labels. Just use the regular words as they appear in the menus and dialogs. You will notice that the syntax itself makes it clear where the name of something starts and ends.
- While many might think that I named the system so that it would have an acronym that promotes Linux. They would be wrong. I just named it what I named it and only later realized that the acronym rhymes with "penguins." I stuck with it because I have a friend who collects penguins simply because they are cute. You know who you are.
- Who knows, perhaps some smart programmer will figure out a way to use this notation system as a scripting language. Their script processor could simply read these instructions and do the operations just as a human would. This way the same text instructions could be used by both humans and computers. Someone could even create a feature where a user could simply copy and paste some of these instructions into a dialog box to instantly set the appropriate settings for a particular task. Or people could create buttons with these steps listed in a field in a configuration dialog box and when the user clicked on the button, then all the steps would be performed. I know, there is VBA and there are macros available in many programs. However, VBA and macros are rather obtuse for the beginning - or even intermediate - user while a list of steps in GCGUINS is very easy for novice users to read and understand.
License Notice:
Copyright 2007, Grant Sheridan Robertson
I, Grant Sheridan Robertson, give everyone the right to use this notation system for free in any documentation they write. Simple newsgroup or forum posts - where someone is just telling someone else how to do something - can use GCGUINS without any attribution because that would just become too cumbersome and I don't want to turn everyone into copyright violators. If your blog has absolutely no advertising on it whatsoever, then you can use GCGUINS without attribution. All commercial content, from Blog articles to published books, must give attribution using my full name "Grant Sheridan Robertson," the full name of the system, "Grant's Concise GUI Notation System," as well as the acronym, "GCGUINS," and say that it rhymes with "penguins." Yes, even Microsoft® books. So, a commercial blog article that uses GCGUINS must give attribution, but comments about that article don't have to go to the trouble. (I consider any publication of any form that makes money - including but not limited to: through advertising, subscriptions, selling merchandise, or donations - to be commercial.)
In addition, full books must include some form of this description and this license in an appendix so readers can learn to use GCGUINS for themselves. You are welcome to copy the text verbatim or modify it to suit your needs with the exception that you cannot modify this license. Web sites and blogs must either include this description or link to one somewhere else. I cannot guarantee that I will always have one available to link to, so you might as well just copy this text.
Finally, it won't do you much good to modify the syntax itself because then you would just confuse your readers who are already familiar with it. The goal, after all, is to make it easier for everyone to use their computers. A consistent system helps everyone.
Grant's Concise GUI Notation System (GCGUINS) More Login
Grant's Concise GUI Notation System (GCGUINS)
Slashdot Top Deals