Editorial Styleguide for gsa.gov and InSite · Web viewUse three or four letters as needed to...

Editorial Styleguide for GSA.gov and InSite

December 5, 2012 GSA.gov and InSite Editorial Styleguide, Version 6 of 19

December 5, 2012

IntroductionThis Editorial Styleguide for GSA.gov and InSite clarifies GSA’s usage on the web.

The guide is:• organized alphabetically in topical sections;• an evolving document written to ensure consistency and clarity;• reviewed on a regular basis by a team of GSA writers and editors, with changes made as necessary.

In the digital realm, changes in punctuation, grammar, and style have evolved that challenge traditional print usage. On the web, readers do not typically read the same way they would read printed documents – users just scan quickly.

In order to meet web user demands for quick task performance and scannability, we have considered user dynamics. On a computer screen, punctuation can be hard to read and thus can create confusion in sentence meaning. The new technology has had a massive influence on the English language, not to mention that the Internet has created new words, phrases and meanings.

For GSA employees who write, edit and post content on any GSA website, this guide is available at on InSite at the GSA.gov Specific Resources page

The guidance provided here applies equally to all GSA websites. It is not specific to one technology platform or the other. Small differences in the process of creating navigation titles are noted.

Write in Plain Language • People should be able to understand what is written for them the first time they read it. • Plain language is easy to understand and quick to consume, relying on short sentences and everyday

words with their everyday meanings. • The The Plain Language Action and Information Network (PLAIN) (www.plainlanguage.gov) has

good resources for creating content that it is easy to read and understand. The Federal Plain Language Guidelines are particularly useful – link: http://www.plainlanguage.gov/howto/guidelines/FederalPLGuidelines/index.cfm?CFID=441912&CFTOKEN=4f38d82051e6e5be-898011D2-1372-4138-C963F7A00141DED3&jsessionid=883014e3173001d5479a2257607a2539524d

• Also see GSA guidance on GSA InSite: Planning, Writing, & Maintaining Your Content

References1. This guide uses The Associated Press Stylebook and Briefing on Media Law, Perseus Publishing,

2009 as the primary source for most usage. Some of the items listed in this guide include references to the AP Stylebook, for those wanting to read about a topic in greater detail. These references are presented beneath a topic heading as such: (AP, page #)

2. The primary resource for web terminology and usage is The Web Content Style Guide, McGovern, Gerry, Norton, Rob, and O’Dowd, Catherine, Pearson Education Limited, 2002. References to it are presented beneath a topic heading as (WCSG, page #).

3. Sometimes special usage for GSA–specific programs is necessary and is noted within these pages as GSA.gov Accepted Style.


http://insite.gsa.gov/portal/category/530253

http://www.plainlanguage.gov/howto/guidelines/FederalPLGuidelines/index.cfm?CFID=441912&CFTOKEN=4f38d82051e6e5be-898011D2-1372-4138-C963F7A00141DED3&jsessionid=5e309b6a2d36c10c8f471b2b52185b361d2c

http://www.plainlanguage.gov/howto/guidelines/FederalPLGuidelines/index.cfm?CFID=441912&CFTOKEN=4f38d82051e6e5be-898011D2-1372-4138-C963F7A00141DED3&jsessionid=5e309b6a2d36c10c8f471b2b52185b361d2c

http://insite.gsa.gov/editorialservices/Desktop/Editorial%20Styleguide%20for%20GSA

http://insite.gsa.gov/portal/category/530253

ContentsTopics are hyperlinked: scroll, control, and click to follow link

A. ABBREVIATIONS AND ACRONYMS AND JARGON 4

B. ADDRESS, DATE, DIRECTIONS, TELEPHONE, AND TIME FORMATTING 41. Address............................................................42. City, State........................................................43. Dated Lists.......................................................44. Dates – Month Day, Year................................45. DC....................................................................56. Decades............................................................57. Directions: north, south, east, west..................5

8. Fax...................................................................59. FY 10 or fiscal year 2010................................510. Month Names...................................................511. State Names.....................................................512. Telephone Numbers.........................................513. Time.................................................................614. U.S...................................................................6

C. ELEMENTS OF PAGES ON GSA.GOV AND GSA INSITE 615. GSA logo as sitewide identification................616. “Microsites” and Microsite Titles....................617. Navigation Titles.............................................6

18. Page Titles.......................................................619. Teasers.............................................................7

D. GSA AND GOVERNMENT REFERENCES 720. Agencywide.....................................................721. Branches of government..................................722. Central Office..................................................723. E-Government (E-Gov)...................................724. egovernment (egov).........................................725. e-Tools.............................................................726. Expo.................................................................827. federal..............................................................828. government......................................................829. Governmentwide..............................................8

30. GSA.................................................................831. GSA.gov & InSite............................................832. GSA-managed, GSA-leased or GSA-owned...833. nation...............................................................834. Region..............................................................835. S/SO/R.............................................................836. Schedule...........................................................937. Service.............................................................938. Staff Office......................................................939. State.................................................................9

E. NUMBERS AND NUMBERING 940. Numbered lists format.....................................941. Numerals..........................................................9

42. percent..............................................................9

F. PUNCTUATION, GRAMMAR AND TYPOGRAPHIC STYLE 1043. Ampersand (&)..............................................1044. Bulleted and Numbered Lists........................1045. Capitalization.................................................1046. Colon..............................................................1047. Comma...........................................................1048. Dash...............................................................1149. Hyphens.........................................................11

50. Italics..............................................................1151. Quotation Marks in Headlines.......................1152. Semicolons.....................................................1253. Sentence spacing............................................1254. That/which.....................................................1255. Underlining....................................................12

G. TITLES 1256. Titles of books, magazines, reports...............12 57. Titles for GSA.gov.........................................12

H. WEB REFERENCES 1258. email..............................................................1259. HTML............................................................1360. HTTP.............................................................1361. Internet...........................................................1362. online.............................................................13

63. PDF................................................................1364. URL...............................................................1365. World Wide Web...........................................1366. web.................................................................13

I. HYPERLINKS 14

J. STYLING LINKS TO DOCUMENTS FOR DOWNLOAD 15

K. WRITING IN FIRST, SECOND, OR THIRD PERSON 16


L. ASSESSING READABILITY 17


A. Abbreviations and Acronyms and Jargon

Acronyms and jargon can often confuse readers. Do not assume customers are familiar with GSA’s acronyms and jargon.

Avoid acronyms and jargon when possible and always identify acronyms on first use. (e.g., The Department of Homeland Security (DHS) is in Washington, DC.)

On GSA websites, the acronym GSA can be used throughout the websites. It is not necessary to spell out U.S. General Services Administration. The GSA Star Mark and title that appear at the top of every page are considered the first usage and the acronym GSA can be used throughout the websites.

Do not overuse an acronym within a page; look at Pronoun section on p. 16. See “Acronym and Jargon Lookup” on GSA InSite homepage for the approved terms. Regarding abbreviations, they are permitted in lengthy navigation titles, forms, charts, and tables. Since the purpose of using abbreviations is to shorten the character count (letters and spaces)

abbreviations are NOT followed by a period. Example: GWAC not G.W.A.C. New abbreviations must be approved prior to use.

B. Address, Date, Directions, Telephone, and Time Formatting

1. Address The GSA Central Office address should be written as:

NameTitleOrganization (spelled out), Room NumberU.S. General Services Administration1800 F Street, NWWashington, DC 20405-0002

Use the same format for other GSA locations.

2. City, State (AP, pages 262, 329) Use a comma between the city and the state and after the name of a state (e.g., The Selma, Alabama, group saw the governor.) except at the end of a sentence: The group saw the governor in Selma, Alabama.

3. Dated Lists Order dated lists from the most current to the oldest.

4. Dates – Month Day, Year(AP, page 275,181 (months) Use commas after the day and the year when using the month, day, and year (e.g., January 10,

2008, will be a…). Do not use a comma if the year and the month only are used (e.g., January 2008 will be a…) are

used. Do not use a comma after the day when only the month and day are used (e.g., January 10 will be a…).

Do not use 04/10/09 or similar constructions – unless it is necessary for a table configuration or format on the web.


5. DC For the District of Columbia, write DC without periods, in all cases.

6. Decades (AP, page 81) Do not use an apostrophe when writing a decade (e.g., 1960s).

7. Directions: north, south, east, west (AP, page 85) Use lowercase for compass directions. When designating regions, capitalize North, South, East, and West. (e.g., Wind from the east will

cool the Northwest.)

8. Fax When a fax number is included in contact information, in the GSA content management system it

will apply the label “Fax.” Use the (123) 123-1234 format. In this context, Fax will automatically be capitalized.

Within body text on the web, it is not capitalized, unless it starts a sentence. When fax stands alone as in a table, chart or in contact, capitalize fax.

9. FY 13 or fiscal year 2013 Leave a space between FY and the year. On the web it is difficult to see apostrophes. Use the last two digits of the year – without an

apostrophe -- when FY is used. (e.g., FY 10). When spelling out fiscal year, use a lowercase letter at the beginning of each word and write out

the entire year. (e.g.: In fiscal year 2013, my budget will be higher.)

10. Month Names Always spell out the name of a month when using alone or with a year alone. In tabular material, use these three-letter forms without a period: Jan, Feb, Mar, Apr, May, Jun,

Jul, Aug, Sep, Oct, Nov, Dec.

11. State Names(AP, page 262) When referencing one of the 50 United States: Eight states are never abbreviated (Alaska, Hawaii, Idaho, Iowa, Maine, Ohio, Texas, and Utah)

except when used in a full address with the ZIP code. Four states are commonwealths instead of states (Kentucky, Massachusetts, Pennsylvania, and

Virginia). Always spell out the name of a state when it stands alone. (e.g., I was born in Kansas in 1988.) Abbreviations may be used in tables and when writing addresses. When referencing the government of a state, use lowercase “state.” (e.g., Due to the flooding, the

state government has closed offices for 48 hours.) When referring to our nation’s capitol, use Washington, DC as the preferred usage – no periods

between D and C.

12. Telephone Numbers (AP, page 268) Use the (123) 123-1234 format. If there is an extension number given, use Ext. 123.


13. Time Write time as 1:00 a.m. EDT, or 3:30 p.m. EDT. Use figures except for noon and midnight. Avoid such redundancies at 10 a.m. this morning.

14. U.S.(AP, page 285) There is no space between the letters in U.S. Use this abbreviation only as an adjective (U.S. General Services Administration or It is a U.S.

territory.) If referring to the United States, spell it out: I was born in the United States.

C. Elements of Pages on GSA.gov and GSA InSite

15. GSA logo as sitewide identification Because the GSA Star Mark is prominently displayed on the top of every page, the abbreviation,

“GSA,” or the words U.S. General Services Administration, should not be included in page titles.

16. “Microsites” and Microsite Titles Pages on GSA.gov and InSite are collected into topical areas or categories with their own left

navigation. This navigation reflects the hierarchy of topic and subtopic pages. Such a self-contained unit of content with its own left-hand navigation is often referred to as a

“microsite.” The microsite title appears at the top of the navigation column. It is a label, not a link. The microsite title is limited to 40 characters and is configured only by site administrators. Navigation titles within the left column should avoid repeating the microsite title. (See below)

For example, within the Region 6 microsite, use “Community Outreach,” not “Heartland Region Community Outreach,” because “Heartland (6)” appears as the microsite title. Page titles (see Item 17 below) may reiterate the microsite title because they appear apart from the navigation column and also on search results.

17. Navigation Titles The title that appears as the link in the left-hand navigation and in cross references is the

navigation title (Note: this is distinct from the page title that appears at the top of the page.) Navigation titles are limited to 40 characters (including spaces). An ampersand (&) may be used to replace “and” in the navigation title if necessary because of the

space limitations. The ASTO Content Management System CMS imposes the navigation title “Overview” on the

top page in the left navigation of a microsite. Other navigation titles are configured by content creators.

The ASTO Web Content Management InSite CMS system allows greater flexibility for the navigation title of the first page of a microsite.

When creating a navigation title, consider the context of the left navigation in which it appears. Avoid repetition and redundancy with the microsite title. See Item 18 below.

18. Page Titles A page title is the complete title of the content that appears when a webpage is displayed. Page titles are limited to 256 characters, including spaces.


Capitalization: use title case – initial capital for the first word of the title and for all other words of four or more letters (e.g., “The Lions and the Tigers,” not “THE LIONS AND THE TIGERS” and not “The Lions And The Tigers”).

Do not use an ampersand as a replacement for “and” in the page title unless it is part of an organization’s formal name.

The page title is displayed as a link to the page in Search results. Page titles may include the microsite title.

19. Teasers On the web, teasers are displayed as the search result when a customer searches for information. Write teasers to fully describe the information customers will find on a page. There is a 150 character maximum (letters and spaces) on teasers. Teasers should be complete sentences or thoughts.

D. GSA and Government References

20. Agencywide Do not use a hyphen in word. This also applies to *governmentwide, statewide, and sitewide.

*However, if referring to the official title of the GSA Organization “Office of Government-wide Policy”, Government-wide should use a hyphen.

21. Branches of government Use lowercase to refer to the executive, judicial and legislative branches of the government.

22. Central Office Capitalize the first letter in each word of “Central Office” when referring to the GSA Central Office.

23. E-Government (E-Gov) Always use a hyphen with this and similar proper names of official government program titles. When referring to the president’s Electronic Government Initiative or the president’s

E-Government (E-Gov) Initiative, capitalize the first letter in each word or abbreviation. Other examples: E-Authentication, E-Clearance, E-Grants, E-Loans,

E-Payroll, E-Records Management, E-Rulemaking, E-Training, E-Gov Travel, and E-Vital. When in doubt, go to www.egov.gov. Note: the exception to this rule is email, as it has become generic web term and is not a proper

noun. It is not hyphenated. (The Web Content Style Guide, p 91.)

24. egovernment (egov)(Web Content Style Guide, P.90) For all other uses of egovernment activities, the first letter in each word or abbreviation should be

lowercase. This has become generic web usage. At the beginning of a sentence, use “Egovernment” or “Egov.” Avoid using this generic term.

25. e-Tools The term is always written with a lowercase “e” and an upper case “T” – because this is the

official program title.


At the beginning of a sentence, use E-Tools. Use “e-Tools” because it refers to GSA-owned, off-portal sites with transactional capabilities

that receive enhanced marketing opportunities on the portal. Links to e-Tool cross references are encouraged throughout GSA.gov. Use E-TOOLS when it is an infoblock on GSA.gov, displaying on the right side of the page.

26. Expo In references to GSA Expo, capitalize the first letter in Expo. Do not capitalize all letters.

27. federal (AP, page 106) Use lowercase (e.g., federal website), except when federal is part of a title or an organization’s name (e.g., Federal Trade Commission).

28. government (AP, page 122) Always use lowercase (e.g., government website). Do not abbreviate the word except when used in the navigation title and has a character limit.

29. GovernmentwideDo not use a hyphen in this word or other similar words: agencywide, sitewide, and statewide.

30. GSA Consider the homepage the first use of General Services Administration and use the acronym on

the rest of the site. On GSA websites, refer to General Services Administration as GSA. Avoid using GSA as part of a program name unless it is part of the official program title (e.g.,

GSA Advantage!, using “GSA” again is redundant since the content is on the GSA website.)

31. GSA.gov & InSite Make the letters “GSA” upper case when referring to the GSA.gov portal, (e.g., “I visit GSA.gov

whenever I want to check per diem rates.”) When referring to the URL, use http://www.gsa.gov, all lowercase. Capitalize both the “I” and the “S” in InSite. When referring to the URL, use http://insite.gsa.gov, all lowercase.

32. GSA-managed, GSA-leased or GSA-owned Do not use “GSA-controlled.”

33. nation Use lowercase to write the word nation, unless referring to a specific “Nation” (e.g., Nation of Islam).

34. Region Capitalize the first letter in “Region” when referring to a GSA Region. Capitalize “The” when writing The Heartland Region. “The” is part of this Region’s name.

35. S/SO/R This is a GSA acronym for Service, Staff Office and Regions. It should only be used on GSA InSite or internal correspondence, as it is an agency acronym.


http://insite.gsa.gov/

36. ScheduleCapitalize the first letter in “Schedule” referring to a GSA Schedule.

37. Service Capitalize the first letter in “Service” referring to a GSA Service (i.e., FAS, PBS).

38. Staff Office Capitalize the first letter in each word of “Staff Office” when referring to a GSA Staff Office.

39. State When referencing the government of a state, use lowercase.” (e.g., Due to severe flooding, the

state government has closed offices for 48 hours.) See State Names, Item 11, for additional guidance on presenting names of the 50 states.

E. Numbers and Numbering

40. Numbered lists format Write numbered lists as:

1. First item2. Second item3. Third item

Do not write numbers using parentheses or extra periods such as 1) or 1.). Note: For more on numbered lists see: Bullets and Numbered Lists on p. 10

41. Numerals Spell out numbers up to and including nine. Write numbers over nine as figures. If using numbers over 10 and under 10 in the same sentence, follow the rules above. (They had a

fleet of 10 station wagons and two buses.) Never start a sentence with a numeral, unless it is a calendar year. (e.g., 2001 was an eventful

year.) If large numbers must be spelled out, use a hyphen to connect a word ending in “y” to another

word (twenty-one). It is better to recast the sentence to avoid beginning with a number. When two numbers appear together, use a hyphen after the second number (e.g., six one-liter

bottles).

42. percent(AP, page 211) Use one word, lowercase. It takes a singular verb when standing alone. (e.g., The teacher said 60 percent was a failing

grade.) Also use a singular verb with “percent” in “of” constructions. (e.g., He said 50 percent of the membership was there.)

In copy, spell it out rather than use the symbol, and always use numerals with percent. (For example, 1 percent, 2.5 percent)

In charts and tables the percent sign (%) is acceptable. (An exception to AP)


F. Punctuation, Grammar and Typographic StyleDetailed guidance on typography is in the Graphics Styleguide for GSA.gov available on InSite.

43. Ampersand (&) (AP, page 15) Use the ampersand only when it is part of an organization’s formal name or when it is in the

navigation title on the web, or when it is needed to save space. Do not use it as a replacement for “and” in the page title or in the page content. (See also

Navigation Title, Item 7 and Page Title, Item 8.)

44. Bulleted and Numbered Lists Bullets and numbered lists are great devices to use on the web as it is easier to scan and absorb

information. Two bullets or numbers are the minimum number for a list. Note: See also Semicolons, p. 12 Use parallel construction – bulleted or numbered items should all start with either a noun or a

verb. Note the uses of punctuation. For example:

The GSA.gov team: Provides distributed authorship; Develops content collaboratively; and Writes concise, meaningful content.

Periods are not necessary after short phrases or single words in a list if the introductory statement is grammatically complete without the items in the bulleted list. For example:

The animals in the zoo have unique characteristics, such as: Long Tails Horns Stripes Trunks

If you need to present content in sequence, use a numbered list, as such:

Here is the recipe for cucumber sushi:1. Cut fresh cucumbers into thin strips.2. Add two teaspoons of rice vinegar and one-quarter teaspoon of salt to three

cups of steamed rice.3. Spread the rice on seaweed, tip with cucumber strips, and roll tightly.4. Slice the sushi roll into bite-sized portions.

45. Capitalization (AP, page 43) Use lowercase unless there is a compelling reason to capitalize. (See also Titles on p. 276)

46. Colon The most frequent use of a colon is at the end of a sentence to introduce lists, tabulations, texts,

etc. When presenting a list, use a colon at the end of the introductory phrase followed by bulleted items. See “Bulleted and Numbered Lists” above.

47. Comma Use a comma after the last item in a series, an exception to AP. (chair, table, and rug…)


When a conjunction such as “and,” “but,” or “for” links two clauses that could stand alone as separate sentences, use a comma before the conjunction. (I had roast beef with dinner, but potatoes were not on the menu.)

The comma always goes inside quotation marks.

48. Dash (WCSG, page 73) A dash is not a hyphen as it has different uses. Use an “em” dash — a long dash with spaces between the dash and the letters on either side of it.

Treat the ellipsis similarly. Use dashes to denote abrupt changes in thought, within a phrase that otherwise would be set off

by commas, for attribution, in datelines and in lists to introduce individual sections.

49. Hyphens Hyphens can separate or connect individual words. When two words are combined to describe a

noun, it’s hard to know when to use a hyphen. If the description comes AFTER the noun, don’t hyphenate. (Mother is strong willed.) If the description comes BEFORE the noun, use a hyphen when either of the words used alone

wouldn’t make sense by itself. (She is a strong-willed mother.) Use this construction for a series of descriptions before the noun: He received a 10- to 20-year

prison sentence. If one of the words ends in “ly,” you never need a hyphen. When “self” or “quasi” is one of the words, always use a hyphen. The fewer the hyphens the better. Use them only when not using them would cause confusion. When in doubt, check the dictionary.

Examples: Hal is the ex-president of the company. The tourist noticed anti-British sentiment. The investigators discovered a stone-like substance. Samson was antifeminist. They are conducting a bicoastal romance. I am having a mini-crisis while caring for these multitalented children. Be overcautious if your date is underage.

50. Italics (WCSG, page 130) Different web browsers can make italics difficult to read on a computer screen and should be

avoided in general text. Use italics in the titles of books, films, plays, long poems, periodicals including newspapers,

magazines and journals (the New York Times), works of art, names of ships, foreign words and expressions (nom de plume).

Italics may also be used when writing letters, words, and terms when they refer to the letter, word, or term itself, (e.g., an “em” dash is the width of the letter m).

Try not to use italics and quotations marks on the web together, “as such.”

51. Quotation Marks in Headlines In headlines, AP style is to follow story style in spelling but use numerals for all numbers and

single quotes for quotation marks. On the web, see Titles guidance. (AP, page #276)


52. Semicolons (WCSG, page 199) Use these sparingly. They are used to separate phrases in a list or to indicate two parallel parts of

a sentence. Sentences that use semicolons can be more difficult to understand. Avoid semicolons if possible on the web because they get lost on a screen. Use semicolons with bullets, if the bullets are part of a complete sentence, such as:

The report included such items as: indexing and cataloging for reindeer; the management of forests and wetlands for reindeer habitat; and the diet for reindeer in different parts of the world.

53. Sentence spacing Use one space between sentences, which is standard for web and print publications.

54. That/which (AP, page 271) and (WCSG, page 212) AP and WCSG provide a number of ways to decide whether to use “that” or “which.” Rule of Thumb: if the construction of the sentence makes it logical to put a comma after the last

word before “which” or “that,” use “which.”

55. Underlining Do not use underlined text on websites unless the text is a hyperlink. (See Section I, Hyperlinks.)

G. TitlesFor information on page titles, navigation titles, and category titles, see Section C.

(AP, Pages 276-277) Formal titles are capitalized when they are directly before an individual’s name (Administrator

Jones, President Obama, Regional Administrator Scott). Titles are not capitalized when used in a generic sense, “The president issued a statement,” or

when they are set off by commas, such as “the associate administrator, John Smith…” Titles are not capitalized when they serve as occupational descriptions: astronaut John Glenn,

singer Ray Charles, architect Frank Jones.

56. Titles of books, magazines, reports Capitalize the main words. Use regular font (not bold, not italics) in quotation marks for article titles, report titles, chapter

titles, and shorter poems, (e.g., “Lawmaker Proposes New Recovery Funding.”) For web guidance, see Titles in Section C and Italics in Section F.

57. Titles for GSA.gov See Section C, Elements of Pages, above.

H. Web References

58. email (Web Content Style Guide, Page 91) Do not use a hyphen in this word. It has become a generic web description.


All lowercase unless at beginning of a sentence.

59. HTML (AP, page 134) Capitalize unless it is in a web address.

60. HTTP (AP, page 134) Capitalize unless it is in a web address.

61. Internet (AP, page 141) Initial capital this proper noun.

62. online Use one word, lowercase.

63. PDF (AP, page 210) Capitalize all of the letters in this acronym unless it is the file name for a specific document (e.g., elephants.pdf). It stands for portable document format, but the acronym is acceptable in all references, including the very first use.

64. URL (AP, page 285)Capitalize all of the letters in this abbreviation.

65. World Wide Web When using the term, World Wide Web, capitalize the first letter in each word. It is a proper noun.

66. web (Web Content Style Guide and GSA Accepted Usage) Use lowercase. This is controversial with many print and web editors, but with so many confusing uses we

recommend capitalizing the proper title World Wide Web only – and other references should be lowercase. We believe that the term has become a generic word, such as cola, aspirin, yo yo, and zipper.

Example: I have heard so much about the World Wide Web that I want go shopping on the web, get my own email address, and create my own website.

Examples of the term web: web address web based (The application is web based. This is a web-based application) web browser web portal web server webcam webcast webmaster webpage website


I. Hyperlinks An important component of the information that a webpage can provide is links to other pages and other websites. The structure of pages set expectations for where those links will lead. The left-hand column displays links to other pages in the category where the page is located (navigation). A right-hand column typically contains links to information supplementary to the page but usually outside that category or to another website.

This guidance if for hyperlinks that appear in the primary content areas of GSA.gov and InSite pages.

Format consistently: Links in body content of are underlined and colored blue. This style will be automatically imposed on all links created within the CMS web editor. Also, NO text anywhere on the site other than links should ever be underlined. Note: customized styles are used on links in the right column blocks and on the homepage, tab and umbrella pages.

Use understandable wording: The “link label” (the words that are actually clickable) should be meaningful and long enough to be understood, but short enough to minimize wrapping. Single-word links usually provide enough meaning only in the context of a label or heading. Nine to ten words are acceptable, but links can often be shorter and remain clear.

“Click Here” is not necessary: Including the words “click here” in hard-coded links is not recommended. Users of mobile phones will not click on links but will select or follow them.

Avoid wrapping text: Try to keep links on one line and as short as possible while remaining clear about what is being linked to. Entire sentences are not necessary and can be difficult to read if they wrap to a second line. For example the link in, “There are many business opportunities in the Southeast Sunbelt for companies working in the technology sector…” is difficult to read.

Place links at the end of paragraphs to improve scannability: Appending the link to the end of paragraph (instead of embedding it into the text) can help avoid wrapping and aids visitors scanning the page for links – particularly if there are many similar links on the page. Including a “greater than” (>) symbol is recommended in these cases. Business opportunities in the Southeast Sunbelt >

Use pointers: The greater than symbol “>” should be used as a consistent visual cue in links at the end of a paragraphs, or at the bottom of a page. For example, a link to an extended biography from a brief message could be written as follows.More about James Smith >


J. Styling Links to Documents for DownloadLinks to documents in the File Manager are added to the web content to make files available for download. The text of the title of the document should be linked to the file, followed by information about the file type and size.

These links should be presented consistently throughout GSA.gov using the following style:

Title of File [File extension - File size File size unit]Some examples:

Download Handbook of Office Practices [PDF - 21 KB]

For more information, consult the Project X Guidelines [DOCX - 1.2 MB]

2012 Financial Results [XLS - 892 KB]

Note that the file extension is in all upper case, the file size is no more than three digits (e.g.: ### or #.#), and the file size unit is all upper case (e.g: KB, MB, GB).

Use three or four letters as needed to represent format correctly (DOC, DOCX, PPT, PPTX, XLS, XLSX, etc.)

Square brackets should be used and the file extension separated from the size by a space, hyphen, space. Only the file title is linked, not the sentence preceding it, nor the file information following it.

AVOID THESE COMMON MISTAKES:(.PDF - 21 KB) Use square brackets, not parentheses. Do not use a period preceding file type.[PDF - 1,208k ] Do not use more than three digits, in this example convert to 1.2 MB. No space

before closing bracket. [ZIP File - 2.1MB] Don't include the word "File". Do insert a space between file size and unit.[PPTX, 1.2 mb] Use a hyphen (not a comma) to separate file type and size. Use upper case for

size unit.[Word - 2.4 MB] Use file extension not application name (DOCX not Word)[PowerPoint - 198 KB]

LIBRARIES OF DOCUMENTSWhen a number of documents relate to a particular topic, it is useful to collect them into tables. Use the guidance above for format and size entries in the tables as illustrated below. Note that separate rows are used to present different formats of the same document. An example of a full page library is at http://www.gsa.gov/portal/content/104033


http://www.gsa.gov/portal/content/104033

K. Writing in First, Second, or Third PersonUse the First and Second Person for GSA.gov

Use first- and second-person pronouns when writing content for GSA.gov. Using pronouns allows us to comply with the Plain Writing Act of 2010, makes the actor clear, and makes the tone more personal. Specific guidance follows:

Feature stories: Write content for feature web news in second person.

FAQs: Write questions in first person and answers in second person.

Audience-specific content: Identify your audience and then address them directly. For example, you can say “.if you are a federally registered lobbyist, please submit your proposal to…”.

You can also use a page title or header to make your audience clear. For example, on a page within the Careers section, “For College Students and Recent Graduates,” use the second person because the content addresses a particular audience segment.

Use second person for information about events and registration for events.

Content with multiple audiences: On pages that address multiple audiences or general, undifferentiated site visitors, use headers to identify your audience. For example, in a page relevant to both vendors and customers, add a header “For Vendors and Customers” and use the second person.

Use the First and Second Person for InSite

Write content for InSite in the first and second person.

When writing FAQs, write questions in first person and answers in second person (i.e., How Can I . . .? You can . . .)

Clarification of Personal Pronouns Singular Subjective Possessive Objective1st person I my, mine me

2nd person you your, yours you

3rd person hesheit

hisher, hersits

himherit

Plural 1st person we our, ours us

2nd person you your, yours you

3rd person they their, theirs them


L. Assessing Readability InSite and GSA.gov exist to communicate information to readers on the web. Making that information easy to use increases its value.

Web readers usually scan text for keywords and phrases. They skip text that doesn’t interest them or catch their attention.

Since online visitors seek easy-to-read, easy-to-scan content, write to meet their needs.

Use familiar words. Keep sentences and paragraphs short. Meaning can get lost in complex sentences on a computer screen, so avoid lengthy paragraphs unless they are absolutely necessary for regulatory or legal reasons.

Two Ways of Checking Readability

The first and best way is to ask a test reader who is unfamiliar with the content to read it. A typical reader will probably understand the content if the test reader understands it. Ask a spouse, a friend, or even better, a sixth through eighth grader to read your content. Remember, some of the audiences visiting GSA.gov use English as a second language. They may have limited English language skills, and should be able to read content on GSA.gov easily.

The second way is using a software-based readability test. A readability test counts the number of syllables and words in a sentence. Then it counts the number of sentences in the text and determines the reading difficulty. A readability test should be used as a guide for rewriting, not an absolute determinator of readability. You can use Microsoft Word to check a page’s readability.

Instructions for Assessing Readability in Microsoft WordTo display readability statistics:

1. On the Tools menu, click “Options”, and then click the “Spelling & Grammar” tab.2. Select the “Check grammar with spelling” check box.3. Select the “Show readability statistics” check box, and then click OK.4. Click “Spelling and Grammar” on the Standard toolbar.

When Word finishes checking spelling and grammar, it displays information about the reading level of the document. You’ll know whether you need to make sentences shorter, or substitute more common words.


Editorial Styleguide for gsa.gov and InSite · Web viewUse three or four letters as needed to...

Documents

Transcript of Editorial Styleguide for gsa.gov and InSite · Web viewUse three or four letters as needed to...