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.

Basics:

• 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.

• 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 or 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 … what's that word? … oh yeah, concise.
  • 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.
  • 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 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 ;
  • <General> ;
    
    • [x] Confirm conversion at Open ;
    • [Web Options] ;
      
      • <Browsers> ; Options, [x] Allow PNG as a graphics
        format ;
      • <Pictures> ; Screen size = 640 x 480 ;
      • [OK] ;
  • <Spelling & Grammar> ;
    
    • Spelling, [ ] Check spelling as you type
    • Grammar,
      
      • [ ] Check grammar as you type ;
      • [ ] Check grammar with spelling ;
    [OK] }

• 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:

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 - either through
advertising, subscriptions, 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.

---

This post is Copyright © 2009 by Grant Sheridan Robertson.