Sunday, June 21, 2009

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.

No comments:

Post a Comment