Skip to content

Examples Style Guide

Jump to bottom
Michael DuBelko edited this page Oct 16, 2019 · 10 revisions

This guide describes how to style and format the text and images in a Gaffer example.

  1. Backdrops
  2. Style
  3. Grammar
  4. Punctuation
  5. Word choice
  6. Spelling
  7. Nodes
  8. Plugs
  9. Data
  10. Interface
  11. Actions and gestures
  12. API
  13. Other formatting

1. Backdrops

An example's titular Backdrop

1.1 Backdrop title text

A Backdrop title should be clear and short. Regular Backdrop titles should be in sentence case, while the titular Backdrop should be in title case. A Backdrop's title shouldn't be wider than the Backdrop itself. If you need the extra space, create a second, wider Backdrop with no text but the same color, and place it behind the first.

The example name in the title Backdrop should match exactly how it appears in the Examples menu in Gaffer, and vice versa.

1.2 Backdrop title formatting

Backdrops titles should use the following formatting:

Backdrop purpose Text Color
Title of example Example: [Example Name] —
Note Note: [Note title] Color3f( 0.3479, 0.4386, 0.5 )
Tip Tip: [Tip title] Color3f( 0.3, 0.5, 0.4605 )
Other backdrop [Backdrop title] —

1.3 Backdrop body text

Each Backdrop with text should be 40 units wide for optimal line width. Note that this measure is in dimensionless Qt units.

You can initialize a Backdrop to use the correct size with this command in the Python Editor:

root["Backdrop"]["__uiBound"].setValue( imath.Box2f( imath.V2f( 0, 0 ), imath.V2f( 40, 20 ) ) )

Once initialized, manually adjust the height of the Backdrop to encompass its text.

1.4 Titular backdrops

All examples must have a titular Backdrop, with a properly-formatted title, and with body text describing what the example is showing and giving a brief rundown of how it works. For example:

In this graph, we show a procedurally-generated Macbeth chart. We load a "MacbethTexture" reference script to generate a texture in OSL, pass the texture to a standard Appleseed shader, and then assign it to a 5:3 ratio plane. To preview the scene in an IPR:

  1. Select the InteractiveAppleseedRender node.
  2. Click play.
  3. Select the Catalogue node.
  4. The IPR will display in the Viewer. To frame the image, hover the mouse cursor over the Viewer, then hit F.

1.5 Correlating nodes with Backdrops

When describing or pointing out a node inside your example with a text Backdrop, encompass the Backdrop and the node by placing a second Backdrop with the same color, and resize it to cover both the node Backdrop and the node. For example:

Backdrop with node

2. Style

2.1 General style

Never forget that you're directly writing to a person. If it helps, pretend you're writing an email to a coworker who's new to Gaffer.

When illustrating an idea or concept, try to provide one salient but simple and generic example that hits at the core of your point. Your example shouldn't be more complicated than the idea you're trying to convey. Examples that are overly esoteric, or assume too much prior knowledge risk distracting the user. If your example isn't immediately recognizable to the majority of the users, it is useless.

3. Grammar

2.1 Instructions

Write instructions in the imperative tense.

Correct Incorrect
click the node to select it clicking the node will select it

4. Punctuation

4.1 Lists

In lists with more than two items, use the Oxford comma.

Correct Incorrect
Lions, tigers, and bears. Lions, tigers and bears.

4.1 Acronyms and contractions

Don't mark acronyms, initialisms, abbreviations, and contractions with periods.

Correct Incorrect
OSL O.S.L.
Encoded using FACS. Encoded using F.A.C.S.
comp work comp. work

4.2 Ellipsis

Only use ellipsis (...) when referring to wildcards in a path or set expression, or to indicate that you are omitting parts of code. Don't use them to trail off or hedge your words.

Correct Incorrect
Your render will be queued on the farm. Your render will be queued on the farm...
any `gaffer execute ...` command

5. Word choice

5.1 Slang words and phrases

Avoid colloquial and slang words and phrases.

Correct Incorrect
lots gobs
to start starter for ten

5.2 Latin words and phrases

Don't use Latin/legal words, phrases, and abbreviations. The only exception is "etc", which you can use at the end of a list in a sentence.

Correct Incorrect
such as i.e.
in other words
in place in situ
for example e.g.
specifically to wit
primitives such as spheres, cubes, cones, etc

5.3 Author pronouns

When referring to yourself (the author), Gaffer's developers, or the collective efforts of the project as a whole, use the royal "we" and "our".

Correct Incorrect
we will demonstrate how to I will demonstrate how to

5.4 Audience pronouns

When speaking directly to the user, use "you" and "your".

Correct Incorrect
Select whichever color you prefer. The user should select their preferred color.

6. Spelling

6.1 Dictionary

Word spellings should follow Canadian English, using the following patterns that differ from American or British spelling:

Preferred spelling patterns
serialize
centre
licence
travelling
fulfill
dialogue
program

The exceptions to this are words integral to VFX that conventionally (or predominantly) use American spellings, or that occur extremely frequently in the API, and would require too much effort to vary per context.

American spelling exceptions
color
Color3f

Note: The above table is subject to change.

6.2 Software names

Spell project names, software, and technologies the way their authors have established, even if they defy convention.

Correct Incorrect
macOS MacOS
FFmpeg FFMPEG

6.3 File extensions

When referring to a file extension, but not the technology that drives it, enclose it in backticks, put it in lower case, and prefix it with a period.

Correct Incorrect
Arnold `.ass` file. Arnold ASS file.

7. Nodes

7.1 Referring to nodes

There are two contexts where you can refer to a node by name: the Graph Editor and the API. In both cases, write the name exactly as it appears in context, like so: "[node name] node". When referring to multiple nodes in a row, put "[node name] nodes" only for the last node. If the node's name in context obfuscates its purpose, invoke its module as well. Do not use the node name as it appears in the node menu.

Correct Incorrect
an Instancer node an Instancer
Create two more Instancer nodes. Create two more Instancers.
add to the `root["Instancer"]` node add to `root["Instancer"]`
OSL's AddColor node OSLAddColor node
the Appleseed point_light node the asPoint node
Connect the Sphere node to the Instancer, Parent, and Group nodes. Connect the Sphere to the Instancer, Parent, and Group.

7.2 Modifying node names

When modifying a node's name to indicate its purpose, append an underscore (_) and then any extra words in camel case (specifically Pascal case), so as to preserve its original name. The only exception is the Box node, which you can provide with a completely custom name, so long as it's in Pascal case.

Correct Incorrect
Camera_Render renderCam
Group_Lights Group_lights

8. Plugs

8.1 Referring to plugs

There are three contexts where you can refer to a plug by name: the Node Editor, the API, and the Graph Editor. In all three cases, write the name exactly as it appears in context, like so: "[plug name] plug". When referring to multiple plugs in a row, put "[plug name] plugs" only for the last plug.

For a plug in the API, format it as inline code.

For a plug in the Graph Editor, use the name visible when you hover the cursor over it.

Correct Incorrect
check the Expand Data Window plug check expandDataWindow
call the method on the `expandDataWindow` plug call the method on the expandDataWindow plug
In the Graph Editor, connect the Sphere node's out plug to the Group node's in1 plug. Connect the Sphere node's Out plug to the Group node's In plug.

9. Data

9.1 Strings and numbers

Format string and number values as inline code.

Correct Incorrect
Set the Radius plug to `2.3`. Set the Radius plug to 2.3.

9.2 Multi-line strings

Format multi-line strings code blocks.

Correct Incorrect
```
There are more things in heaven and earth, Horatio,
Than are dreamt of in your philosophy.
```		 "There are more things in heaven and earth, Horatio,
Than are dreamt of in your philosophy."

9.3 Scene and file paths

Format scene and file paths shorter than a line width as inline code. Include the forward slash (/) in full paths. Format scene and file paths longer than the line width as code blocks.

To disambiguate path snippets in a sentence, add "parent/child location" for scene paths and "directory"/"sub-directory"/etc for file paths.

Do not use wildcard characters (* or ...) to indicate you have omitted part of the path.

Correct Incorrect
Type `/asset01/REN` into the Parent plug. Type "/asset01/REN" into the Parent plug.
the attributes of the `REN` child location the attributes of `REN`
```
/extremely/long/path/to/a/particular/location
```		 `/extremely/long/path/to/a/particular/location`

9.4 Set and channel names

Enclose set and channel names in double quotation marks.

Correct Incorrect
the "REN" set the `REN` set

10. Interface

10.1 Referring to editors

Refer to the editors exactly as they appear in the interface.

Correct Incorrect
Viewer viewport
Primitive Inspector PrimitiveInspector

When referring to an editor in general, use the definite article ("the"). When covering a task that requires a layout with multiple editors of the same type, use indefinite articles ("a", "an", "some", "any") as needed. In the majority of contexts, it's safe to assume the user's layout has at least one of each editor.

Examples
the Graph Editor
the Node Editor
Open a new Viewer.
Open two more Viewers.

10.2 Referring to context menus

When instructing the user to select a top-level entry in an unnamed or context-specific menu, use the form "[Action/gesture] the [widget], then select [entry] from the context menu."

Examples
Right-click the node, then select Set Color from the context menu.

10.3 Context menu names

Use the following menu names:

Menu Name
Node menu the node menu
Node context menu the node context menu
Named context menus the Expansion menu
the Selection Mask menu
the Drawing menu
etc

11. Actions and gestures

11.1 Action verbs in instructions

Use the following action-phrasing correspondence when instructing the user to perform an action in the interface. Never use the word "set" to describe an action.

Action Verbs and phrasing
left-clicking click [button name or image]
right- and middle-clicking right-click the node
clicking and dragging click and drag a marquee around the nodes
middle-click and drag the node onto the Viewer
clicking with a modifier key SHIFT-click the other node
choosing an item from a drop-down list select Color from the list
choosing a menu bar item Go File > Settings.
choosing a context menu item select Scene > Hierarchy > Group
inputting text type `user:custom` into the plug
hovering the cursor hover the cursor over the Graph Editor
keystroke hit ENTER

12. API

12.1 Referring to code snippets

Format references to modules, API code, and Python Editor code snippets as inline code. This includes API node names, plug names, methods, types, and data values.

Examples
the `imath` module
To return the value of the Radius plug, use the `getValue()` method.
the plug can be accessed at `root["Sphere"]["radius"]`

12.2 Referring to code blocks

Format entire lines of code as code blocks.

Examples
```
root["Sphere"]["radius"].getValue()
```
```
import imath
root["Sphere"]["transform"]["translate"].setValue( imath.V3f( 0, 1, 0 ) )
```

13. Other formatting

13.1 Referring to keyboard keys

When referring to a keyboard key, put each key in upper case. When depicting a key combination, separate each key with a space, a plus (+), and another space: "CTRL + C".

When referring to the typical control key, spell it "Ctrl" to represent both Ctrl in Linux and the Command key (⌘) in macOS. If macOS's actual Control key is required, draw the user's attention to its atypical use.

Correct Incorrect
hit ENTER hit Enter
hit CTRL + ALT + C hit Ctrl-Alt-c
Clone this wiki locally