Insight Style Guide
This guide explains how to structure and write insights.
Insights are the individual messages that ThinkUp delivers as a stream to users, giving them information about their activity. The name "insight" was chosen because that's exactly what a person should get from looking at one: some insight into what their activity, or their interactions with their connections, really means.
Insights should be created with a mind to what emotion they are attempting to evoke, and it's critically important that the design, writing and experience of interacting with insights stay true to ThinkUp's values of being positive, encouraging, challenging, smart and unexpectedly delightful.
An insight consists of three parts: a prefix, a body, and an optional attachment. See a screenshot with a sample of existing insights.
Insight prefixes consist of 2 to 4 words in sentence case, typically end in a colon (rarely an exclamation point) and should be unique to that particular insight. They serve as the title to the insight. The prefix should capture the essence of the insight's purpose with personality and flair, and differentiate insights to make the stream easy to scan. They're deliberately designed to be secondary to the insight body, so assume prefixes are slightly subordinate to the body of the insight, even though they precede it.
Examples include:
- Time machine:
- Made the list:
- New 7-day record!
- Stuff you liked:
- Post of the week:
Insight prefixes are blue by default, though it's possible to define a higher level of emphasis in an insight for particularly important or exciting achievements and announcements. High-emphasis insight prefixes are shown in green, to contrast from the usual blue prefixes.
By default, green high-emphasis prefixes should be for events or insights which occur so rarely that a user would never see more than one per day.
The most evocative way to distinguish insight prefixes is by the use of the small icons which begin each prefix. ThinkUp uses the Font Awesome icon library to provide hundreds of choices for insight creators to use to illustrate their insights. These icons are particularly critical on mobile devices, where insight prefix icons are isolated in a prominent area of ThinkUp's stream display.
Take a look at the full list of Font Awesome icons to see the choices. And of course, insight prefix icons should be chosen with a mind to minimizing the re-use of icons already incorporated into other insights.
An insight's body copy should be 1 or 2 sentences summarizing a point that makes the user feel something or offers a call to action. The following are guidelines for writing effective insight body copy that matches existing insights. Note that examples below are intended to address isolated details and may lack features illustrated by other examples, eg. bolding.
Avoid sentence fragments. Each sentence should be a complete thought which ends in the appropriate punctuation (such as a period).
- Don't: Lamarr Wilson's video touched a nerve 55% of viewers liked it and 45% disliked it
- Do: Lamarr Wilson's video touched a nerve! 55% of viewers liked it and 45% disliked it.
There is one exception to this rule: When the insight text prefaces an insight attachment, like a list of posts or users. In that case, it can be a fragment that ends in a colon. An example might read "On this day in years past, @ginatrapani liked:" followed by a list of posts in the insight attachment.
Use exclamation points sparingly, and only for truly unusual, exciting insights.
Refer to the user to whom the insight applies by network user name.
- Don't: You are on a new list, awesome-developers.
- Do: @dougw is on a new list, awesome-developers.
Preface Twitter handles with an @ sign.
Insights use the network user name of the account because an individual ThinkUp user might have several different services connected to their ThinkUp login. Also, it makes insights shareable/readable to the outside world.
Wherever possible, link usernames, posts, lists/groups, etc, to the relevant URLs (profile page, permalink, etc.) at the source network.
One of the tricky parts of writing without using second-person words like "you" is that ThinkUp does not capture information about gender, if any, of the network user to whom the insight refers. So, find phrasings which avoid this issue instead of calling attention to it.
- Don't: @dougq is on a new list, awesome-developers, which is his/her 411th list membership.
- Do: @dougw is on a new list, awesome-developers, which makes a grand total of 411 lists.
Also avoid using the their/themselves plural form to refer to people, because it sounds really awkward:
- Don't: @dougw's tweet got 15 favorites today, double their 30-day average.
- Do: @dougw's tweet got 15 favorites today, double the 30-day average.
An insight should use network-specific verbs and nouns. You don't tweet on Facebook, and you don't like on Twitter. Examples:
- tweet/post/status
- update/checkin
- retweet/reshare/reblog
- liked/faved/+1'd
- comment/reply.
The InsightTerms class does this conversion for you.
- Don't: @ginatrapani's tweets averaged one reply every 7 days last week.
- Do: @ginatrapani's tweets averaged 1 reply every 7 days last week.
Format potentially large numbers.
- Don't: @ginatrapani is on a new list, bloggers, bringing the total to 4854 lists.
- Do: @ginatrapani is on a new list, bloggers, bringing the total to 4,854 lists.
An exception to this is that insights which use multiples should use words to spell them out, if possible.
- Don't: @dougw's tweet got 15 favorites today, 2x the 30-day average.
- Do: @dougw's tweet got 15 favorites today, double the 30-day average.
- Don't @anildash favorited 157 tweets yesterday.
- Do: @anildash favorited 157 tweets yesterday.
Communicate an insight the way you'd tell a friend (versus a robot reciting statistics). Don't be afraid to be funny or lighthearted.
- Don't: @jack favorited 1 tweet every 1 hour 1 day ago.
- Do: @jack favorited 1 tweet every hour yesterday.
- Don't: 2 tweets were favorited by 10 users.
- Do: 10 users favorited 2 tweets.
This is one of the most fundamental aspects of ThinkUp's "personality" as an application. Not every bit of feedback is going to be information that a user wants to hear about their social networking activity, so insights should phrase things affirmatively where possible.
- Don't: John's status update got 13 likes, down from 15 on last week's best update.
- Do: John's status update got 13 likes, almost as many likes as the high of 15 last week.
Drop unnecessary words (without sacrificing clarity).
Humans have an innate emotional response to faces, especially ones they recognize. If you can show avatars or user pictures inline to tell the story of an insight, do it!
ThinkUp has a defined palette for details within Insights and their attachments; These should apply to any charts, graphs or visualizations you generate.
| Color Name | Hex Value | Uses |
|---|---|---|
| ThinkUp Blue | #00aeef | |
| ThinkUp Green | #31c22d | |
| purple | #a923b5 | |
| gray | #7d7d7d | |
| black | #000000 | Insight prefix text |
| yellow | #f8f8b1 | |
| dark gray | #979795 | |
| off-white | #faf9f2 | |
| #cccccc | Insight body text; insight prefix emphasis | |
| #3A87AD | Default insight prefix background | |
| #468847 | Emphasized insight prefix background | |
| #0088CC | Insight links | |
| #005580 | Insight links, hovered |
TODO - Discuss:
- user, post, and list links
- charts and other visuals (Google Charts API, D3)
- attachment expansion while showing top item and not.
- setting the expansion button icon
Developer guidelines for coding insights.
- insightname.php and insightname.tpl
- Available view templates that list users, posts
- TestOfInsightName.php and all_plugin_tests.php
- These files can be automatically generated by running:
./extras/dev/makeplugin/makeinsight NameOfInsight YourName YourEmailAddress
- If there is no possibility of new data since last crawl, check if insight has already been generated before generating it.
- Optimize your SQL. Run EXPLAIN, consider indexes, and larger data sets.
- Curb the number of queries the insight runs to generate.
- Title and description for Insights Generator settings page
- Scheduling insights