-
-
Notifications
You must be signed in to change notification settings - Fork 2
UX Writing Guide
Please write UI text content for ATD according to the rules outlined below.
- Brand Voice Tone
- Brand Voice Chart (includes Example Text)
- Glossary of Terms
- Nomenclature Audit
- A section for previous work and research
The ATD brand writing tone has been described as:
- trustworthy and simple language
- Talking to - you
- 3rd grade / children’s book-short sentences, conversational
- Funny (Example: Medium. Guides for laymen. Conversational tone; straightforward story-telling. Not funny but not too serious; super inviting to beginners; but still professional)
- Casual
- Respectful
- Enthusiastic
Version date: 09-07-2022 by Matt Kushin
How to Use the Voice Chart:
- Decide which product principle you want to emphasize with a piece of text.
- Use the aspects of voice for that product principle when writing or editing the text.
- 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 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. |
Source: Access the Data Voice Chart - Example Text
A working document to catalog terms to use and to avoid in ATD UX Writing. This will help create consistency in UX Writing for ATD.
Language | When We Use It | Why it Matters | Example |
---|---|---|---|
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 | When It Was Used | Alternative Suggestion(s) | Rationale |
---|---|---|---|
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. |
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 |
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 |
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 |
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 |
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 | ||||||
[email protected]. | ||||||
readme | ||||||
Jessica Sand | reference to a readme |
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 | ||||||
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 |
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 |
First Header | Second Header |
---|---|
Content Cell | Content Cell |
Content Cell | Content Cell |
Command | Description |
---|---|
git status | List all new or modified files |
git diff | Show file differences that haven't been staged |
This is a working document, please compile any questions and suggestions and bring it up during our meetings. Thank you!
- MVP - Closed
- V1: Data Catalog - ON HOLD
- Domain Knowledge
- Research
- UX Writing Guide
- Site Design
- Software Development (redirects to CKAN repo)
- Operations Engineering (redirects to CKAN repo)
- PM Guide