UX Writing Guide

Welcome to Access the Data's UX Writing Guide

Please write UI text content for AtD according to the rules outlined below.

The sections in this Wiki have a specific order from top to bottom. Each section serves as a foundation of knowledge for the next section. This way, you can easily learn about how we write, and easily go to any section as a resource when needed.

Please update "Version Date: MM-DD-YYYY by -Name-" if there's a new update. All changes can be seen through "Page history" if needed.

To jump to a specific section, click on one of the links below. There is a "Back to Top" button after each complete section to make your life easier.

Here's what you will find in this wiki:

• Brand Voice Tone
• Brand Voice Chart
  • Example Text
• Glossary of Terms
  • Language to Use
  • Language to Avoid
• Nomenclature Audit
  • Findings and Recommendations
  • UX Recruitment Language
  • Hack for LA Page
  • AtD One Sheet
  • GitHub Main Page
  • Website
  • Website Architecture
• Research
• Markdown Tips for this Wiki

Brand Voice Tone

Version date: 09-29-2022 by Matt Kushin

The AtD brand writing tone has been described as:

• trustworthy and simple language
• Talking to - you
• 3rd grade/children’s book-short sentences, conversational

Back to Top

Brand Voice Chart (includes Example Text)

Version date: 09-07-2022 by Matt Kushin

How to Use the Voice Chart:

1. Decide which product principle you want to emphasize with a piece of text.
2. Use the aspects of voice for that product principle when writing or editing the text.
3. If you are unsure of which product principle fits best for a piece of text, use more than 1 product principle to write multiple versions of the text. Discuss and decide which works best.

Product Principles	SIMPLE	TRUSTWORTHY	EMPOWERING	FRIENDLY
Concepts	Useful. Clear. Efficient. Easy.	Data transparency. Data access. Community-driven.	Data can help every community member learn, grow, hold government accountable, and make change.	Accessible & inclusive. Welcoming. Inviting.
Vocabulary	Plain, non-expert descriptions that emphasize action, results, and ease of use.	Professional, objective, serious. A community hub (catalog of open-access data), not a data broker (filter). Refer to AtD and Hack for LA in third person.	Possibilities and empowerment for all skill & knowledge levels. The joy of learning. Collective efforts & impact. The user drives the experience.	Inclusive, language that is encouraging and supportive. Community, not bureaucracy. Refer to AtD and Hack for LA in first person, not third person. Don’t assume English proficiency.
Verbosity	Less is more. Avoid adjectives & adverbs.	Enough words to have accurate information.	{not specific}	Conversational.
Grammar	Simple sentences or phrases. Verb-object, imperative clause ("Find data;" "Get Help").	Past tense when discussing history & accomplishments. Present or future tense when discussing identity, ongoing or future projects and possibilities. Complex and compound sentences okay. Active or passive voice is okay. Complete sentences or phrases okay.	Present and future tense. Affirmative sentences or phrases. Active voice when discussing the user.	Complete sentences.
Punctuation	Use periods, commas. Avoid question marks. Avoid terminal punctuation for instructions. Use colons for "Note" items and note-like items.	Use periods, commas. Avoid question marks. Avoid terminal punctuation for instructions.	Question marks, commas, periods, parentheses. Dashes instead of colons.	Question marks, commas, parentheses. Dashes instead of colons.
Capitalization	Title case for titles, buttons, headings.	Title Case. Capitalize proper nouns.	Title case.	Sentence case.
Tips	Emphasize action: - "do" - "find" Emphasize results: - "impact" - "change" Emphasize ease of use: - "easy" - "available" Choose the simpler term: - "use" not "utilize" - "curious" not "inquisitive"		Emphasize collective efforts & impact: - "teamwork" - "with" - "together" Put the user in the driver’s seat: - "you can" - "your community" - "learn" - "grow" - "influence" - "change" - "power up" - "help" - "learn" - "goals" - "achieve" Emphasize joy of learning: - "build" - "learn" - "discover" - "practice" Note: Avoid "citizen" – not all who use AtD are native or naturalized U.S. citizens.

Back to Top

Example Text:

Source: Access the Data Voice Chart - Example Text Back to Top

Glossary of Terms

A working document to catalog terms to use and avoid in AtD UX Writing. This will help create consistency in UX Writing for AtD.

Language to Use

Language	When We Use It	Why it Matters	Example
AtD	Acronym for "Access the Data."	A consistent acronym to reference Access the Data.	AtD provides open-access data to local Los Angeles communities.
government data; government data sources	Optional description of the type of data offered on the open-data catalog.	Note: Synonym for "public data" and "open-access data"	Access the Data has identified that it is imperative to increase citizen’s access and understanding of local government data in order to be effective advocates for their communities.
open-access data; open data	Reference to the accessibility of data being offered on AtD.	Note: Synonym for "government" and "public data"	Access the Data is a free catalog of open-access data.
open-data catalog	Reference to the AtD data catalog of open-access data.		Explore our open-data catalog.
open	To describe public data or government data.		The MVP will consist of a website that hosts a catalog of open government data sources.
public data; public data sources	Short optional description of the type of data offered on the open-data catalog.	Note: Synonym for "government data" and "open-access data"

Language to Avoid

Language	When It Was Used	Alternative Suggestion(s)	Rationale
ATD	Inaccurate acronym for "Access the Data."	AtD	The accurate acronym has been decided for consistency and accuracy.
citizen	Reference to users.	community member	The term "citizens" was being used to refer to users. To ensure inclusive language, it is important to avoid assuming that all users are native or naturalized U.S. citizens.
data literacy	Originally, Access the Data was going to have an educational module. This is on hold. In our current iteration, we do not want to imply that Access the Data is a place.	[none: avoid]	Agreed at 08-31-22 meeting that the term should be discontinued because project no longer is focusing on providing data literacy.
education; educational resources	Reference to AtD providing educational information that enhances data literacy.	[none: avoid]	No longer providing education on AtD.
modules	Reference to educational data literacy modules.	[none: avoid]	No longer going to provide modules on AtD.
open source data; open-source data; Open-data sources	Descriptor of the type of data one is accessing via AtD.	open-access data; public data; open data; open government data; open government data sources; public data sources	It was stated by a project team developer, Judson, that the term "open-source" is inaccurate as it pertains to the data, as open-source refers to the source code. But, the project is "open-access." The term "open-access data" should be used instead.
resource catalog	Reference to the AtD data catalog.	open-access data catalog; open-data catalog	Clarification Issue: the term "resource catalog" is vague.
tutorial	Reference to tutorials for learning data literacy.	[none: avoid]	No longer providing education on AtD.
workshop	Reference to educational workshops for learning data literacy.	[none: avoid]	No longer providing education on AtD.

Back to Top

Nomenclature Audit

Findings and Recommendations

Version date: 09-20-2022 by Matt Kushin

Findings
Finding #1 - Accuracy
The nomenclature audit revealed several inaccuracies where the copy had not been updated since the project pivot. These included mentions of:	- live workshops - recordings of workshops - data literacy education - modules
Suggestion:	Copy across public-facing documentation, perhaps, should be edited to remove mention of data literacy and education until we are pivoting back to include data literacy components
Priority:	Medium
Completed?	No
Finding #2 - Consistency
Descriptive terms consistently used to describe Access the Data on the Hack for LA one sheet and GitHub main page were missing from the wireframe "about us" text. They were: "government data" and "Los Angeles."
Suggestion:	Update "about us" text to use these terms to ensure the Access the Data website reflects language used elsewhere
Priority:	Medium
Completed?	Yes
Finding #3 - Inclusive Language
The term "citizens" was being used to refer to users. To ensure inclusive language, it is important to avoid assuming that all users are native or naturalized U.S. citizens.
Suggestion:	Use a more inclusive term such as "community member"
Priority:	Low
Addressed?	No
Finding #4 - Accuracy
The term "open source data" was used to describe the project in the UX Recruitment email.
Suggestion:	Remove term and replace with a term such as "open-access data"
Priority:	Low
Addressed?	No
Suggestion:	Start an Access the Data glossary of terms to use (e.g., open-data catalog, government data sources) and to avoid (e.g., data literacy, open-source data, citizens)
Priority:	Low
Completed?	In progress

Back to Top

UX Recruitment Language

Version date: 09-12-2022 by Matt Kushin

Source: AtD: Screener Survey Recruitment

	Noun Phrases	Notes	Verb Phrases Notes	Notes	Additional Noteworthy Adjectives	Notes
Who AtD is - the People	Hack for LA	described as a "brigade of Code for America"
	brigade of Code for America	What Hack for LA is described as
	volunteer	AtD UX Researchers describing selves as volunteers
	Access the Data
What the AtD Project is	resource of information and training	Reference to what AtD is			Transparent	describes project
	workflow	How AtD is completing this project			open-source	describes project
	project	Descriptor of what AtD is; "this project"
	free resource	AtD is described as a free resource
	open-source data (Accuracy Issue: It was stated by a project team developer, Judson, that the term "open-source" is inaccurate as it pertains to the data, as open-source refers to the source code. But, the project is "open-access." The term "open-access" should be used instead.)
What the AtD Team is Doing			developing	Verb to describe the building of AtD
References to Users	community advocates (Consistency Issue: Same thing referred to in different ways. "advocates" was Matt's word. May be removed for consistency purposes.)	Reference to target audience
	community activists (Consistency Issue: Same thing referred to in different ways.)	Reference to target audience
	communities	what users are impacting
What Users are Doing	advocacy	as in, the work community advocates are doing	interactions with data
	initiatives	What users are trying to support	impact	"use data to impact your community"
	involvement	- Term to describe actions users are taking - synonym for advocacy - "community involvement" - "involvement in any LA local communities"	helping	Describes the user's ability to help the project
	work	synonym advocacy	advocating	Verb to describe actions users take
	community work	synonym advocacy
How the AtD Project Can Help Users	data-drive decisions	What we are claiming can be accomplished with the data	access open-source data
	desired skills (Accuracy Issue: No longer going to provide modules. Should we be alluding to educational resources? It seems that we aren't going to provide those anymore.)		support	Reference to how data can be used to "support your initiatives"
	literacy (Accuracy Issue: No longer going to provide modules. Should we be alluding to educational resources? It seems that we aren't going to provide those anymore.)
			collection	as in, data collection
			analysis	as in, data analysis
			use	as in, using data

Back to Top

Hack for LA Page

Version date: 09-13-2022 by Matt Kushin

Source: Access The Data - Hack for LA

	Noun Phrases	Notes	Verb Phrases Notes	Notes	Additional Noteworthy Adjectives	Notes
Who AtD is - the People	Access The Data	in page title
	Access the Data
	Current Project Team
	All-Time Contributors
What the AtD Project is	project (Consistency is Good: Same thing referred to the same thing each time.)	"The Access the Data project"	accessing	accessing modules and self-teaching content
	modules (Accuracy Issue: No longer going to provide modules.)	to address data literacy needs	self-teaching
	website (Consistency is Good: Same thing referred to the same thing each time.)		find
			use
What the AtD Team is Doing	data literacy education (Accuracy Issue: Remove term "data literacy" from all text. Agreed at 08-31-22 meeting.)		identify where data literacy education is most needed

Back to Top

AtD One Sheet

Version date: 09-13-2022 by Matt Kushin

Source: Access the Data One Sheet

	Noun Phrases	Notes	Verb Phrases Notes	Notes	Additional Noteworthy Adjectives	Notes
Who AtD is - the People	Access the Data
	Hack for LA	icon noted at bottom
What the AtD Project is	MVP (minimum viable product)		centralized	"centralized space"	important	it is important to increase citizens' access...
	space	"centralized space"	help
	open government data (Consistency is Good: Same thing referred to the same thing each time.)		use
	educational resources (Accuracy Issue: No longer going to provide modules. Should we be alluding to educational resources? It seems that we aren't going to provide those anymore.)		host
	data
	tool (Consistency is Good: Same thing referred to the same thing each time.)
	project (Consistency is Good: Same thing referred to the same thing each time.)
	catalog of digital resources (Clarity Issue: Term may be seen as vague.)
	website (Consistency is Good: Same thing referred to the same thing each time.)
What the AtD Team is Doing	local government data (Consistency is Good: Same thing referred to the same thing each time.)	affording access to and understanding of	identified		effective
	public website / website		increase	citizens' access	involved
	community	who the public website is for	access	of govt data
	learning	what the public website helps people do	understanding
	open source civic tech community		envision
	key target personas	what AtD has identified	create
	persona development		knowledge transfer
	interviews		growth
	development team		pivoted
	resource catalog (Clarity Issue: The term "resource catalog" is vague. Suggestion: "open-access data catalog" or "open-data catalog" for brevity.)		guiding
	user testing		designed
	product		recruit
			onboard
			coding
			prototype
			building
References to Users	citizens (Consistency is Good: Same thing referred to the same thing each time.)
	community activists (Consistency is Good: Same thing referred to the same thing each time.)
	municipality (Consistency is Good: Same thing referred to the same thing each time.)
	potential users
	people
What Users are Doing	communities	advocate for communities	advocate
	local government data	finding, navigating and understanding	find		easy
			navigate
			understand
How the AtD Project Can Help Users	government policies	deal with issue of	elevate		effective	"effective advocates"
	data	deal with issue of	increase
	data analysis	deal with issue of	encourage
	advocates	be "effective advocates"	find
	adoption
	data sets
	tools
	city
	3rd parties
	publicly available government data sources (Consistency is Good: Same thing referred to the same thing each time.)
	data systems
	applications
	knowledge	increase knowledge
	engagement
	open-source code / data
	existing resources	what people can find via AtD

Back to Top

GitHub Main Page

Version date: 09-13-2022 by Matt Kushin

Source: Access the Data GitHub

	Noun Phrases	Notes	Verb Phrases Notes	Notes	Additional Noteworthy Adjectives	Notes
Who AtD is - the People	Access the Data
	Hack for LA
	brigade of Code for America
	H4LA	short hand for Hack for LA
	the team
	we
	community	reference to team working on project
What the AtD Project is	hypothesis		having
	centralized space		help
	open government data (Consistency is Good: Same thing referred to the same thing each time.)		hosts
	educational resources (Accuracy Issue: No longer going to provide modules. Should we be alluding to educational resources? It seems that we aren't going to provide those anymore.)
	tool	"tool that any municipality"
	catalog (Consistency is Good: Same thing referred to the same thing each time.)
	government data sources (Consistency is Good: Same thing referred to the same thing each time.)	what
	open data literacy resources (Accuracy Issue: Remove term "data literacy" from all text. Agreed at 08-31-22 meeting.)
	product	"one in a series of products"
	Citizen Engagement Collection	the product is identified as being a part of
	website (Consistency is Good: Same thing referred to the same thing each time.)
	open government data sources (Consistency is Good: Same thing referred to the same thing each time.)
	tool (Consistency is Good: Same thing referred to the same thing each time.)
	project (Consistency is Good: Same thing referred to the same thing each time.)
What the AtD Team is Doing	local government data	affording access to and understanding of	increase	citizens' access	imperative
	MVP		access	of govt data
	city of Los Angeles		envision
	Sustainable Development Goals	helping LA achieve these	testing
	United Nations	Refer to the sustainable dev goals	creating
	Target 16.8 of the Sustainable Development Goals	which is defined on the GitHub	helping
			working
			support
References to Users	community activists (Consistency is Good: Same thing referred to the same thing each time.)
	municipality (Consistency is Good: Same thing referred to the same thing each time.)
	citizens (Consistency is Good: Same thing referred to the same thing each time.)
	data experts (Consistency is Good: Same thing referred to the same thing each time.)
	Los Angeles County (Consistency is Good: Same thing referred to the same thing each time.)	ostensibly where users are located
What Users are Doing	communities	advocate for communities	use		easy
	advocate		adopt
	communities		find
	local government data		navigate
			understand
How the AtD Project Can Help Users	government policies	deal with issue of			effective	"effective advocates"
	data	deal with issue of
	data analysis	deal with issue of
	advocates	be "effective advocates"
How the Public Can Participate in Building AtD	GitHub	reference to tools being used	explore		inactive
	Slack	reference to tools being used	read
	Figma	reference to tools being used	see
	Google Suite	reference to tools being used	reach out
	CKAN	reference to tools being used	ask
	Project Management Board	reference to tools being used	manage
	work		join
	purpose		up to
	vision		like
	meetings		self invite
	Slack workspace		introducing
	Slack channel		identifying
	skills		contribute
	onboarding		offer
	required actions		request
	access		complete
	repo		edit
	Team Roster		limited
	Drop-off policy	refer to drop-off policy enforcement	unassigned
	code of conduct	refer to drop-off policy enforcement
	leadership team (PMs + leads)	refer to drop-off policy enforcement
	volunteer	refer to drop-off policy enforcement
	team meetings	refer to drop-off policy enforcement
	two weeks	refer to drop-off policy enforcement
	prior explanation	refer to drop-off policy enforcement
	status	refer to drop-off policy enforcement
	coordination	refer to drop-off policy enforcement
	issues	refer to drop-off policy enforcement
	questions
	comments
	accessthedata@hackforla.org.
	readme
	Jessica Sand	reference to a readme

Back to Top

Website

Version date: 09-14-2022 by Matt Kushin

Source: Access the Data Main Figma

Note:

• Menu was left out of this audit because a new architecture has been developed. See Website Architecture.
• "Modules" and "311 Data" pages were left out because they are being removed in the new website design.

Titles and Buttons	Notes
Titles on Webpages
Grounded in Community, Powered by Data
About Us
Learn at Your Pace
Get Involved
Advance in Data Science
About
Partners
Meet the Team
Get Involved!	Exclamation Point Used.
Contact Us
How Can We Help You Today?	Why are people contacting us - what is the reason we want them to contact? Currently it is about us helping them, presumably about finding data on the website?
Titles on Carousel
Grounded in Community, Powered by Data
Do You Care About Your Community?
Get Involved and Apply Your Data Skills!	Exclamation Point Used.
Explore What Else is Out There
Open Data Success Story: See What Others Are Doing
Titles on Pop-Up Windows
Opening external page	Sentence case.
Buttons
Learn More	Used 3 times.
Tutorials
Volunteer
Data Science Wiki
See the Full Team	4 words. Ideally, 3 or less words in a button.
Explore Opportunities
Resources	Look at more closely. Should it be "Find Resources"?
Continue
Close

	Noun Phrases	Notes	Verb Phrases Notes	Notes	Additional Noteworthy Adjectives	Notes
Who AtD is - the People	Access the Data
	Our team
	Hack for LA
	a team of volunteers
	Hack for LA website
What the AtD Project is	community		grounded
	data		powered
	collaboration
	Los Angeles Department of Neighborhood Empowerment
	Neighborhood Councils
	Los Angeles Mayor's Office
What the AtD Team is Doing	areas where data literacy education within our communities (Accuracy Issue: Remove term "data literacy" from all text. Agreed at 08-31-22 meeting.)		aim
	government policies		identify
	data		address
	data analysis		needed
	data literacy (Accuracy Issue: Remove term "data literacy" from all text. Agreed at 08-31-22 meeting.)		relying
	communities		increase
	live workshops (Accuracy Issue: Remove term "data literacy" from all text. Agreed at 08-31-22 meeting. This is under one of the text boxes on the "About" page.)		hosting
	public data resources		providing access
	recordings of workshops (Accuracy Issue: Reference to education. We have pivoted away from doing education.)
	additional resources on the website
	partners	Names of partners listed
References to Users	citizens	Suggest moving away from "citizens" as all who use it may not be native or naturalized U.S. citizens.
	advocates
What Users are Doing	You	As in "You can see the team at..."
How the AtD Project Can Help Users	change		bring		out there
	community		care
	skills		gain
	public data		using
	community advocacy		through
	decision-making		get
	tutorials (Accuracy Issue: Reference to education. We have pivoted away from doing education.)		apply
	data skills		Explore
	tools		Independently explore
	modules (Accuracy Issue: Reference to education. We have pivoted away from doing education.)		See
	resources		Doing
	Open data success story		uses
	Others		purchase
	MacArthur Park Neighborhood Council		place
	clean street index		Learn
	24 new trashcans		How to
	real-world examples		Advance in data science
	public data tools		used
	curated data science guides and tools		Looking
	real live answer (Clarity Issue: "Live" insinuates that something is occurring in real-time. The text is used on a "Contact Us" page where feedback is not live.)		started
	questions		welcome
	conversation		help
	your message
	team members
	feedback
	ideas
	today
	Name
	Email
	Subject Message
How the Public Can Participate in Building AtD	data skills		itching
	data project		newly developed
	Hack for LA's projects		join
	network		Get involved
	skills		build your network
	data science		grow your skills
	Bold thinkers		Wanted
	changemakers
	Hack for LA website
	details

Back to Top

Website Architecture

Version date: 09-13-2022 by Matt Kushin

Source: Access the Data Sitemap

Note: Text copied directly from Sitemap Google Sheets.

	Primary	Secondary	Tertiary
Home
	About
		Purpose and Mission
		Contact Us
	Data Catalog
	Volunteer
		Join the AtD Team
		Join the Hack for LA Data Science Community of Practice

Back to Top

Website Copy?

asdf

Research

For research information related to UX Writing, go to our Research Wiki to learn more.

Back to Top

Markdown Tips for this Wiki

Tables:

• Add a space before and after each | for cleanliness and legibility. It becomes hard to read the code when every letter and character is clumped together.
• Press enter twice after the last row before adding text or images to give a line break (which means a row of space) below the table. Otherwise it will be included as part of the table.
• To copy the code for the table below, go to "Edit" on this Wiki, scroll down, and copy the code.

First Header	Second Header
Content Cell	Content Cell
Content Cell	Content Cell

Line Breaks:

• These add a "for sure" row of space. Pressing enter however many times may not add the space you want.
• They are helpful in maintaining cleanliness, organization, and legibility.
• Leave space before and after each <br> for organization and legibility.
• Add one line break <br> after each paragraph and after any section where you only need that much space to differentiate between sections.
• Add two line breaks <br><br> after each complete section to give some breathing room before the next new section so that they're easier to differentiate and read.

Paragraphs:

• Press enter twice at the end of each paragraph to add space and start a new line of text. If you only press enter once, it continues as part of the previous paragraph with no space in-between.

Images:

• Only upload images in SVG format. Any other format will not be high enough quality, and will also not be big enough.

For additional resources on how to use Markdown:

• Organizing Information with Tables
• GitHub Docs Basic Writing and Formatting Syntax
• Markdown Cheatsheet (similar to the one below)
• Markdown Here Cheatsheet (similar to the one above)
• Some Random Resource

Back to Top

Formats in this Wiki

Date Format:

• MM-DD-YYYY

Slash Format (also applies for all AtD writing):

• Use / with no spaces before and after the slashes