The following guidelines have been established to provide as much consistency between articles in the handbook as possible. In all cases, proper accessibility of all content is paramount.
Page Titles
Write page titles using the gerund ("-ing") format, like so:
- Creating a New Page
- Updating Drupal Site Modules
- Installing Drupal on OIT Web Hosting
Avoid personal pronouns whenever possible to put the focus on the technical content as opposed to the person who will be carrying out the procedures in the content.
Headings
Headings within articles should start with Heading 2 and sub-headings should follow in numerical order (3, 4, 5, 6).
Headings should only be used when there is significant content that makes sense to be grouped under a descriptive heading. Avoid using headings above a single line or two of content - something that short can likely stand on its own without a heading or be combined into another section of the page.
Additionally, headings should only be used when there is more than one section of content under a parent section, as the purpose of headings is to identify sub-sections. There is no need to use a heading to separate an introductory paragraph from a single block of main content - just insert a horizontal line (HR HTML tag) if you want a visual separation there.
Tags
Tags can no longer be added on-the-fly when adding or updating a page. Instead, contact a site manager will if you think a new tag should be added to the tag taxonomy. Managers should avoid adding tags that are synonyms for existing tags, as this dilutes the tagging system and can make it harder to find all related content, as inevitably multiple synonyms will never be added consistently to all related pages.
For consistency's sake, tags should be in the plural whenever that makes sense (e.g. "user roles" instead of "user role").
Syntax Formatting
-
Paths to administrative control panels should be given in both menu path and URL path format like so:
Configuration -> Development -> Performance (
/admin/config/development/performance)Note the use of bold on the menu path, and the "
Program Code" format for the URL path. -
Use the "
Program Code" format (AKA the "code" HTML tag) for anything that is PHP or shell script code, and use the "Code Snippet" tool (found on the CKEditor toolbar between the table and horizontal line buttons) when providing more than one line of code in an example. -
Also use the "
Program Code" format for any filesystem paths or URL paths. -
Use standard double quotes (") as the primary quote character (avoid stylized quotes), and the single quote (') as your secondary quote character. Double quotes are easier to see and help users to spot important text being grouped by quotes.
-
Highlight in bold the names of buttons, fields, and other on-screen objects that users will be looking for when carrying out instructions. Many users will want to quickly reference instructions while carrying out a procedure, and being able to visually parse out the key button, field, etc. names can greatly speed up this process. Object names highlighted in bold do not need to be quoted as well, as the bold markup will effectively group those words together.
Acronyms and Module Names
With this handbook being a technical reference, many acronyms will inevitably be used. Standard accessibility guidelines should be applied to all acronyms: on the first usage, write out the full phrase or name and then give the acronym in parenthesis. After that, you can then use just the acronym.
Note: "GT" should always be spelled out as Georgia Tech, except in those rare cases where it is part of an official unit or product title. For example, "GT Account Username" is an acceptable usage, as that is the official name for campus user accounts.
Similarly, when referencing modules, give the full human-readable name of the module followed by the machine name in parenthesis, like so, and on first use, make the human-readable name a link to the module's primary page (usually on the Drupal.org website):
Entity Reference (entityreference)
Note: While it is common practice for Drupal module and theme names to not capitalize any word other than the first, for presentation's sake please use standard capitalization rules and capitalize all important words in a title.
Proper Name Usage
Please use the following forms for the given product or service names for consistency and clarity (and for providing better search engine results):
- Drupal (Always capitalize the "D")
- OIT Web Hosting (Don't leave off the "OIT" or condense to "webhosting")
- GT Account Username ("GT Account" can be used after the first occurrence in a section, but do not shorten to "GTAccount")
- Mercury (Hg) Reader (Always include 'Mercury' spelled out in the name with 'Hg' in parenthesis)
For Further Reference
If you have any stylistic questions not addressed here, you can refer to the Georgia Tech Editorial Style Guide.