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.
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).
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.
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.
Also avoid using the their/themselves plural form to refer to people, because it sounds really awkward:
An insight should use network-specific verbs and nouns. You don't tweet on Facebook, and you don't like on Twitter. Examples:
The InsightTerms class does this conversion for you.
Format potentially large numbers.
An exception to this is that insights which use multiples should use words to spell them out, if possible.
Communicate an insight the way you'd tell a friend (versus a robot reciting statistics). Don't be afraid to be funny or lighthearted.
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.
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||Swatch|
|Color Name||Hex Value||Swatch|
Prior to the launch of thinkup.com, an older palette was used to define colors in the app; These are listed here for reference for any legacy insights or UI elements but are deprecated. (Note: The table below has largely been extracted from the CSS and may need clean-up.)
|Color Name||Hex Value||Swatch||Sample Uses|
|black||#000000||Insight prefix text|
|#cccccc||Insight body text; insight prefix emphasis|
|#3A87AD||Default insight prefix background|
|#468847||Emphasized insight prefix background|
|#005580||Insight links, hovered|
TODO - Discuss:
Developer guidelines for coding insights.
./extras/dev/makeplugin/makeinsight NameOfInsight YourName YourEmailAddress