Skip to content

Commit

Permalink
First stab at documentation / style-guide. See #76
Browse files Browse the repository at this point in the history
  • Loading branch information
Lou Huang committed Jan 10, 2014
1 parent 8930278 commit 9995e81
Showing 1 changed file with 39 additions and 0 deletions.
39 changes: 39 additions & 0 deletions doc/style-guide.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,39 @@
# Development FastPass Style Guide

This style guide is a reference for maintainers and contributors to Development FastPass.

## Principles

Gov.UK, built by the Government Digital Service, has an [excellent 10-point list of design principles](
https://www.gov.uk/design-principles) which we would use as a guide for development. While all of these principles should be kept in mind, some of these have been particularly important to Development FastPass and are adapted below.

1. **User needs come first.** Gov.UK's number one design principle is to [start with user needs, not government needs](https://www.gov.uk/design-principles#first), and here, we believe the same. They have also helpfully provided [a guide on focusing on user needs](https://www.gov.uk/service-manual/user-centered-design/user-needs.html).

2. **Don't give all the information, just the most useful information.** Yes, you have a lot of information. Other people have a lot of information. Some of that information can be useful, but only at the right times, or to the right people. Prioritize information that would be the most useful to the most amount of people, so that people are not inundated immediately by too much.

3. **Test user interaction, then iterate.** Software should never be considered "done," but always a work in progress. Building too much in the beginning could be a waste of effort if user testing indicates that no one uses features that seemed like a good idea at the time. However, if you leave off a feature and people request it or seem to need it, start with a small test and then determine how it works.

4. **Keep it simple.** Quoted directly from Gov.UK: "Making something look simple is easy; making something simple to use is much harder — especially when the underlying systems are complex — but that’s what we should be doing."


## Writing Style

In matters relating to finance, law, and governance, it's important to be precise while maintaining clarity. This is achieved by choosing your words very carefully, but clarity should be the most important characteristic. Sometimes it will be necessary to sacrifice language that details the complications and edge cases that may arise.

Yes, your job involves dealing with the complexities of the development review process, but how would you explain it to a five-year old? Can you use only words that are in the list of the [ten thousand most commonly-used words in the English language?](http://xkcd.com/1133/)

The point is not to treat all your customers like children or to make it so children can go through this process. But your customers - especially _new_ customers, the ones most likely to use FastPass - don't need to know all the intricacies until they need to know it, but they do need to know all the giant glaring red flags immediately. Keep the language simple to encourage new business development from your community. Too much text is intimidating and can discourage economic activity.

Don't overload the experience too early with legal jargon - that just intimidates people new to the process and keeps them out of the system.

## Visual Design

(todo)


## User Flow

(todo)



0 comments on commit 9995e81

Please sign in to comment.