Insight Style Guide

Anil Dash edited this page Apr 14, 2014 · 27 revisions

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 Prefix

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.

Insight Body

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.

Write complete sentences.

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.

Use third person.

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.

Link to the source network.

Wherever possible, link usernames, posts, lists/groups, etc, to the relevant URLs (profile page, permalink, etc.) at the source network.

Avoid gender pronouns.

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.

Localize network terms.

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.

Use numerals, not words.

  • 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.

Bold key stats.

  • Don't @anildash favorited 157 tweets yesterday.
  • Do: @anildash favorited 157 tweets yesterday.

Write conversationally.

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.

Avoid passive voice.

  • Don't: 2 tweets were favorited by 10 users.
  • Do: 10 users favorited 2 tweets.

Be positive and encouraging.

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.

Be brief.

Drop unnecessary words (without sacrificing clarity).

Show user icons where applicable.

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.

System Colors

Color Name Hex Value Swatch
ThinkUp Blue #46BCFF
Blue Actions #125C9C
Red Warning #D0021B
Green Success #4CD764
Gray #666

ThinkUp Themes

Color Name Hex Value Swatch
Pea #9DD767
Salmon #FC939E
Creamsicle #FFBB4E
Sepia #C0BDAF
Purple #B690E2
Mint #41DAB3
Bubblegum #F576B5
Seabreeze #44C9D7
Dijon #E4BF28
Sandalwood #FD8560
Caramel #DD814B

Old Colors

Prior to the launch of, 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
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

Insight Attachment

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

Best Practices for Coding Insights

Developer guidelines for coding insights.

File structure

  • 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

Available chart APIs

Clone this wiki locally
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.