├── images ├── fomo │ ├── fomo-initializer.png │ ├── fomo-purchase-event.png │ ├── fomo-signup-event.png │ └── fomo-instantiate-client.png ├── joel_on_software │ ├── What_Time_Is_It.gif │ ├── what-time-is-it-home-page.png │ └── what-time-is-it-login-form.png └── makeup_looks │ ├── makeup-looks-add-look.png │ ├── makeup-looks-lander.png │ ├── makeup-looks-search.png │ ├── makeup-looks-add-makeup.png │ ├── makeup-looks-profile-page.png │ ├── makeup-looks-user-makeups.png │ ├── makeup-looks-individual-look.png │ ├── makeup-looks-add-more-makeups.png │ └── makeup-looks-tutorials-favorites.png ├── README.md ├── enterprise └── upc.md ├── b2c ├── makeup_looks.md └── WhatTimeIsIt.md ├── templates └── boilerplate.md └── b2b_saas └── fomo.md /images/fomo/fomo-initializer.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ryanckulp/feature_spec/HEAD/images/fomo/fomo-initializer.png -------------------------------------------------------------------------------- /images/fomo/fomo-purchase-event.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ryanckulp/feature_spec/HEAD/images/fomo/fomo-purchase-event.png -------------------------------------------------------------------------------- /images/fomo/fomo-signup-event.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ryanckulp/feature_spec/HEAD/images/fomo/fomo-signup-event.png -------------------------------------------------------------------------------- /images/fomo/fomo-instantiate-client.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ryanckulp/feature_spec/HEAD/images/fomo/fomo-instantiate-client.png -------------------------------------------------------------------------------- /images/joel_on_software/What_Time_Is_It.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ryanckulp/feature_spec/HEAD/images/joel_on_software/What_Time_Is_It.gif -------------------------------------------------------------------------------- /images/makeup_looks/makeup-looks-add-look.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ryanckulp/feature_spec/HEAD/images/makeup_looks/makeup-looks-add-look.png -------------------------------------------------------------------------------- /images/makeup_looks/makeup-looks-lander.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ryanckulp/feature_spec/HEAD/images/makeup_looks/makeup-looks-lander.png -------------------------------------------------------------------------------- /images/makeup_looks/makeup-looks-search.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ryanckulp/feature_spec/HEAD/images/makeup_looks/makeup-looks-search.png -------------------------------------------------------------------------------- /images/makeup_looks/makeup-looks-add-makeup.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ryanckulp/feature_spec/HEAD/images/makeup_looks/makeup-looks-add-makeup.png -------------------------------------------------------------------------------- /images/makeup_looks/makeup-looks-profile-page.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ryanckulp/feature_spec/HEAD/images/makeup_looks/makeup-looks-profile-page.png -------------------------------------------------------------------------------- /images/makeup_looks/makeup-looks-user-makeups.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ryanckulp/feature_spec/HEAD/images/makeup_looks/makeup-looks-user-makeups.png -------------------------------------------------------------------------------- /images/makeup_looks/makeup-looks-individual-look.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ryanckulp/feature_spec/HEAD/images/makeup_looks/makeup-looks-individual-look.png -------------------------------------------------------------------------------- /images/joel_on_software/what-time-is-it-home-page.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ryanckulp/feature_spec/HEAD/images/joel_on_software/what-time-is-it-home-page.png -------------------------------------------------------------------------------- /images/joel_on_software/what-time-is-it-login-form.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ryanckulp/feature_spec/HEAD/images/joel_on_software/what-time-is-it-login-form.png -------------------------------------------------------------------------------- /images/makeup_looks/makeup-looks-add-more-makeups.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ryanckulp/feature_spec/HEAD/images/makeup_looks/makeup-looks-add-more-makeups.png -------------------------------------------------------------------------------- /images/makeup_looks/makeup-looks-tutorials-favorites.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ryanckulp/feature_spec/HEAD/images/makeup_looks/makeup-looks-tutorials-favorites.png -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # wtf is this? 2 | 3 | **feature spec** is a new community for product managers to swap best practices for creating technical specs. it's also a place to discover how some of our favorite products and features were conceived. 4 | 5 | ### how it works 6 | 7 | * new to writing specs? start with [our boilerplate](https://github.com/ryanckulp/feature_spec/blob/master/templates/boilerplate.md). 8 | * need some inspiration? [view an example](https://github.com/ryanckulp/feature_spec/blob/master/b2b_saas/fomo.md). 9 | * want to show off? [submit a pull request](#contributing). 10 | 11 | ### recently added 12 | 13 | * [fomo](https://github.com/ryanckulp/feature_spec/blob/master/b2b_saas/fomo.md), a marketing platform 14 | * [makeup looks](https://github.com/ryanckulp/feature_spec/blob/master/b2c/makeup_looks.md), a community for makeup tutorials 15 | * [upc.co](https://github.com/ryanckulp/feature_spec/blob/master/enterprise/upc.md), a search engine for UPC barcodes 16 | 17 | ### navigation and style guide 18 | stash your images inside images/your-project. categorize your spec by industry or category. a few directories have been pre-populated, free to create more. finally, use snake_case when naming folders and files, please. 19 | 20 | ``` 21 | feature_spec 22 | │ README.md 23 | │ contributors.md 24 | │ 25 | └───ecommerce 26 | │ │ your_spec_here.md 27 | │ │ another_spec.md 28 | │ 29 | └───b2b_saas 30 | │ │ yet_another.md 31 | │ │ and_another.md 32 | │ 33 | └───enterprise 34 | │ │ cant_wait.md 35 | │ │ to_read_these.md 36 | │ 37 | └───another_category 38 | │ who_knows.md 39 | │ its_a_mystery.md 40 | ``` 41 | 42 | ### wishlist 43 | 44 | * original feature specs from twitter, facebook, google, etc. 45 | * contributions from celebrity PMs (_i don't know any, i'm just a guy who drinks iced coffee_) 46 | 47 | ### best practices 48 | 49 | 1. **honor code**, please don't prettify an ugly spec to look more badass. 50 | 2. specs are more interesting if linked to the finished product/feature/announcement... especially if the final version was different than the plan. 51 | 3. if you have them, include view-only links to wireframes, early designs, or notes. put us in your shoes! 52 | 4. omissions for security (or embarassment) reasons are OK, but the more raw, the better. 53 | 5. the more obscure the feature, the less interesting. ideally, submissions are tangible. 54 | 6. feel free to include post-mortem notes -- why you made a certain decision choice, what got thrown out, etc. 55 | 5. self promotion OK, just try not to include more than a couple links. 56 | 57 | ### contributing 58 | 59 | 1. fork it 60 | 2. create your spec branch, which may also include a new folder (`git checkout -b my-product-spec`) 61 | 3. commit your changes (`git commit -am 'new spec - your_spec_name'`) 62 | 4. push to the branch (`git push origin my-product-spec`) 63 | 5. Create a pull request 64 | -------------------------------------------------------------------------------- /enterprise/upc.md: -------------------------------------------------------------------------------- 1 | _While not maintained, UPC.co is a live project that has faciliated thousands of searches by retail buyers, and enjoyed 5%+ CTR from paid acquisition for obvious keywords: 'upc database', etc._ 2 | 3 | ### Summary 4 | UPC.co is a third-party resource powered by [Distribute](http://distribute.com), an upcoming marketplace platform connecting commercial buyers with bulk inventory. 5 | 6 | The prpose of UPC.co is to attract potential Distribute buyers without exposing limited inventory or unsophisticated technology. 7 | 8 | ### How it Works 9 | UPC.co will email 1000s of buyers in the consumer electronics, furniture, and toys industries with the offer to “search instantly for bulk inventory.” The results page will yield the exact Item they searched for (via Walmart API) in addition to Distributd’s available inventory and several “sold out” SKUs to tempt buyers to subscribe. 10 | 11 | If a Buyer sees a SKU that interests them, they can subscribe to text alerts for that product category or be emailed a “sell sheet” with additional details such as price and quantity. 12 | 13 | ### Resources 14 | * [UPC api](http://upcdatabase.org/api) 15 | * 3rd party UPC api example script [link omitted] 16 | * Walmart UPC api example script [link omitted] 17 | * API keys [link omitted] 18 | * Industry “sell sheets” [link omitted] 19 | 20 | ### Terminology 21 | * UPC.co -- project name 22 | * Item -- a product SKU comprised of a photo, UPC code, name, description, price, seller name, and quantity 23 | * Buyer -- a commercial buyer, whether a Brand or Broker, etc with bulk inventory purchasing power 24 | * Available -- results table showcasing “available inventory” that exists in our seller database 25 | * Sold Out -- results table showcasing an array of fake Items, marked as “sold out” 26 | 27 | ### Requirements 28 | 29 | As a buyer... 30 | * I want to search for products either by UPC code or Item name to see available inventory in the Project database. 31 | * If I’m interested in an Item, I want to subscribe to email/SMS alerts or have someone call me with more details. I also want * “sell sheets” (referenced in resources) emailed to me automatically. 32 | 33 | As an admin… 34 | * I want to log in and post new product SKUs to reflect my daily available inventory, including image uploads of product shots. 35 | * I want to determine whether an Item is marked Available or Sold Out 36 | * If an Item I’ve previously made Available is no longer available, I want to “archive” or “hide” it so that I can re-activate it later, should the inventory become available again. 37 | * I want to edit the attributes of an Item (quantity/price/name/etc) in case the Available inventory changes. 38 | * I want to send email and SMS “newsletters” showcasing available inventory to UPC.co subscribers, based on the category of goods in which they are interested. 39 | * I want to know how many inquiries an item receives, viewable from my dashboard. 40 | -------------------------------------------------------------------------------- /b2c/makeup_looks.md: -------------------------------------------------------------------------------- 1 | _This is an ongoing project that began in May, 2016, and is projected to finish November 2016_. 2 | 3 | ### Description 4 | Utilitarian platform for makeup lovers to discover and share makeup looks, powered by Choix. 5 | 6 | ### Market Insights 7 | Searching YouTube for specific tutorials requires patience and filtering noise. Makeup Looks will exclusively serve the beauty market and practice admin-side curation to control the quality of content. 8 | 9 | ### Features 10 | * Import instantly from YouTube (MVP: individual video // v2.0: entire channel of videos, as a loop) 11 | *Up/down voting to lend basic curation to crowd-sourcing 12 | * Commenting via Disqus.com 13 | * Authentication with scoping for makeup artists (add videos) && makeup lovers (save tutorials) 14 | * Elastic search (ideally, fuzzy search via algolia.com) 15 | * Auto-complete integration with major makeup SKUs (example API for consumer-packaged goods) 16 | 17 | ### Wireframes 18 | Landing page. Not shown: two folds ie Featured / Recent showcasing 3-4 columns of video thumbnails. 19 | 20 | ![makeup looks lander](https://github.com/ryanckulp/feature_spec/raw/master/images/makeup_looks/makeup-looks-lander.png "Makeup Looks Landing Page") 21 | 22 | Discover / Search results page. Layout available in table (row) or visual grid (panel) format. If search input provided, sort with Algolia. If none provided, sort by Popularity / Recency / Difficulty / Completion Time. 23 | 24 | ![makeup looks discover](https://github.com/ryanckulp/feature_spec/raw/master/images/makeup_looks/makeup-looks-search.png "Makeup Looks Search Results") 25 | 26 | Individual ‘look’ page, embedded YouTube video (we won’t host the actual content) and links to makeup, comments, etc. Rely heavily on YouTube API but also track page views for “hotness” via Impressionist. 27 | 28 | IF the makeup product (via barcode/sku) exists on the Choix store, link there. Else, link to Amazon. Perhaps just link to an executed search on Amazon, vs the actual product page. 29 | 30 | In the case a makeup SKU/UPC can’t be found, allow user to type one in. This will simply yield plain text on a Tutorial/Look page, until an Admin adds additional fields (ie avatar, URL to point to, etc). 31 | 32 | ![makeup looks page](https://github.com/ryanckulp/feature_spec/raw/master/images/makeup_looks/makeup-looks-individual-look.png "Makeup Looks Individual Look") 33 | 34 | Add a look, step 1 of 3. Input link to video, description, and tagging for advanced search filters. 35 | 36 | ![makeup looks add look](https://github.com/ryanckulp/feature_spec/raw/master/images/makeup_looks/makeup-looks-add-look.png "Makeup Looks add a Look") 37 | 38 | Step 2 of 3, add makeups one at a time via auto-complete search. 39 | 40 | ![makeup looks add look](https://github.com/ryanckulp/feature_spec/raw/master/images/makeup_looks/makeup-looks-add-makeup.png) 41 | 42 | Step 3 of 3, after adding all the products for a given look, click ‘Finish’ and get redirected to the Look page. 43 | 44 | ![makeup looks add look](https://github.com/ryanckulp/feature_spec/raw/master/images/makeup_looks/makeup-looks-add-more-makeups.png) 45 | 46 | **Profile Page** 47 | 48 | Vanity URL (default: /{first}-{last}) with similar structure as Tutorial / Look page. Prefer inline editing for this page, ie click a section to change details, vs a separate edit page UI. 49 | 50 | ![makeup looks profile page](https://github.com/ryanckulp/feature_spec/raw/master/images/makeup_looks/makeup-looks-profile-page.png) 51 | 52 | Clicking a dashboard widget renders Tutorials, Favorites, and Products associated with that user. The ‘Videos/Tutorials’ and ‘Favorites’ page should use the same elements as Browsing videos. 53 | 54 | ![makeup looks profile page](https://github.com/ryanckulp/feature_spec/raw/master/images/makeup_looks/makeup-looks-tutorials-favorites.png) 55 | 56 | Finally, the Products page loops through all the [unique] products that the User has identified in their Tutorial videos. 57 | 58 | ![makeup looks all makeups](https://github.com/ryanckulp/feature_spec/raw/master/images/makeup_looks/makeup-looks-user-makeups.png) 59 | -------------------------------------------------------------------------------- /templates/boilerplate.md: -------------------------------------------------------------------------------- 1 | ### description 2 | this is where you define the JTBD (job to be done). ideally this is 1-2 sentences, in [layman's terms](https://en.wiktionary.org/wiki/in_layman%27s_terms). 3 | 4 | ### features 5 | not always appropriate, thus optional. if what you're building is customer-facing (vs infrastructure, devops, etc), it's helpful to provide high level notes on the end-user's experience. 6 | 7 | for example, if you were implementing a payments gateway... 8 | 9 | * ability to trial for 30 days free, without a credit card 10 | * ability to apply coupons (XX days free, X% off, $X off) 11 | * ability to charge or refund pro-rata for < 30 day billing cycle usage 12 | 13 | ### definitions 14 | there are a few words in technology that can become very confusing if not used carefully. words like: client, user, visitor. 15 | 16 | since **writing good technical specs means reducing ambiguity**, it's prudent to use common technology words intentionally. for an added bonus, use Proper casing on words that have been articulated in your definitions section. 17 | 18 | example: 19 | 20 | * Marketer - a customer who is not technical, but ultimately the decision-maker 21 | * Developer - the Marketer's colleague, who will need to schedule time to implement the tool 22 | * User - the Marketer's customer, who will benefit from implementing this tool 23 | 24 | ### user stories 25 | figure out the stakeholders -- who will be affected by the implementation of these requirements? 26 | 27 | describe the benefits (and potentially cons) for each. if there are more than 2-3 stakeholders, it may be better to break the requirements into more specs. 28 | 29 | stakeholder examples: 30 | * marketer 31 | * new prospect 32 | * former customer 33 | * founder 34 | * devops engineer 35 | * customer success rep 36 | * sales manager 37 | * etc 38 | 39 | **story format**: 40 | 41 | 42 | as a _(stakeholder)_, 43 | 44 | i want to ________, 45 | 46 | in order to ____________. 47 | 48 | ### resources 49 | here you can link to materials that increase developer happiness and productivity. stuff like wireframes, early designs, assets (images, fonts, color pallete), etc. pending your technical ability, it can also be helpful to link to specific API documentation, 3rd party resources, open source software dependencies, and more. 50 | 51 | example: 52 | * [wireframes]() from john, still missing XYZ 53 | * [some_cool_gem]() (50 stars on GH, updated weekly, seems legit) 54 | * [another_great_service]() (costs $99 /month but guarantees uptime and wknd phone support) 55 | 56 | ### how it works 57 | it's tempting to get into technical specifications here, but try to resist. instead, explain as linearly as possible how the implementation will behave, when it's live. this should be from the end-user's experience. 58 | 59 | format: 60 | 61 | 1. marketer signs up for platform, and abandons during onboarding 62 | 2. after 3 hours has passed, and marketer has not logged back in, they're sent an email 63 | 3. IF marketer returns to dashboard via the link in email, present them with message "greetings from your inbox" 64 | 4. IF marketer returns to dashboard, but source not attributable, present message "glad to have you back" 65 | 5. when marketer returns to complete tutorial, regardless of source, send to XXX page 66 | 67 | 68 | ### getting started 69 | here we can get technical, and generally go nuts. 70 | 71 | do you need to describe a data model? tell more technical stories? delegeate tasks to different memebers of your team? 72 | 73 | below are optional sub-headers that will help make your spec more modular, readable, and actionable: 74 | 75 | **trade-offs** 76 | 77 | share a few pro's / cons of potential design choices. good PM's provide much of this insight ahead of time, so their dev team can focus on building. and by the way, devs should have 'comment access' to this spec, if a G Doc, so they can ask questions in-line. 78 | 79 | **future considerations** 80 | 81 | this neutral section should assist developers in _reducing technical debt through prevention_. for example, if your marketplacep latform requires a new user role (ie: buyer or seller), but you know that one day you'll need multi-tenancy and teams (many buyers or sellers per shared account), mention that in this section. developers will thank you. 82 | 83 | **potential gotchas** 84 | 85 | you may be writing a spec for a project similar to something you've already done with another team. were there any key learnings from that, which could be shared to reduce research overhead? 86 | 87 | **next steps** 88 | 89 | ah yes, 'action items.' if your team is more than 1-2 people, you may be responsible for delegating stories and sub-tasks to engineers on your team. to make this section fruitful, it's helpful to have a basic understanding of each team members' strengths and interests. does sarah love working with 3rd party apis? is mark already familiar with XYZ open source caching technology? with this in mind, you'll have an easier time kicking off project, quickly. 90 | -------------------------------------------------------------------------------- /b2b_saas/fomo.md: -------------------------------------------------------------------------------- 1 | _This spec was written on April 15, 2016 and the product launched 115 days later on August 9, 2016. Three developers built it, part-time._ 2 | 3 | ### Description 4 | RESTful, Rails API edition of the [Notify ecommerce plugin](https://apps.shopify.com/notify). 5 | 6 | ### Features 7 | * Works on any website 8 | * Flexible server-side callbacks 9 | * Marketer-friendly dashboard for manual, WYSIWYG administration 10 | 11 | ### Resources 12 | * Wireframes 13 | * HTML / CSS 14 | * Proprietary solutions on popular websites 15 | 16 | ### Definitions 17 | 18 | * Event - user-defined activity, such as a sale or upgrade, purchase or signup, etc 19 | * Queue - All the current events being cycled on a website’s front-end 20 | * User - fomo customer 21 | 22 | ### User Stories 23 | 24 | As a marketer, I want to increase on-page conversion on my website. If I sell online courses, I want to show that someone recently purchased my course. If I’m a blogger, I want visitors to know that many people are frequently subscribing to my blog. If I sell a SaaS tool, prospects should see that I get a lot of reviews and offer great support. 25 | 26 | As a marketer, I am not very technical. If I ask my developers to implement an entire API library it could take weeks, thus reducing my chance of becoming a User. Because of this, I would like a simple version of fomo that only requires a code snippet on active pages. Then I can manually add Events to my Queue that are shown with delays, designs, fonts, etc that I specify in the WYSIWYG design settings. 27 | 28 | As a technical marketer or developer, I love working with simple APIs and I take a data-driven approach to growing my business through A/B testing and rapid prototyping. I want to implement fomo quickly to see if my core Events increase, and I need a dashboard + full API suite (with several libraries) to get started. If it works, I will evangelize fomo. 29 | 30 | **Disclaimer** - 31 | This spec is focused on the MVP -- ideas for future versions will be provided in Google Doc comments (right margin, off-page) and then turned into a v2.0 spec after the MVP is completed. 32 | 33 | Version 2.0 ideas are to be discussed exclusively for architectural purposes and not to increase scope of the MVP. 34 | 35 | ### How it Works 36 | 37 | Regardless of whether a User relies on the manual, GUI Queue or the API, they should always have access to the UI and be able to CRUD those Events. A great example of this is Buffer, the social media scheduling tool that lets you POST tweets yet also log into the dashboard and manage with a GUI. 38 | 39 | There are 2 components to running fomo on a website: 40 | 41 | 1. Minified JS snippet that points to code on a CDN, which can only be accessed if called from that domain. 42 | 2. Server-side snippets (a la Mixpanel) for instantiating and POST’ing parameters / options to the fomo backend, which creates an item in the Queue. 43 | 44 | The JS script snippet is required for all users, while the server-side implementation is optional. Added benefits to server-side: pass in variables on-the-fly, Events tracked in real-time, no login / maintenance required, it “just works.” 45 | 46 | **Analytics** 47 | 48 | Fomo will very quickly have a huge database. We’d like to leverage this in the following ways: 49 | 50 | **User dashboards** 51 | 52 | As a marketer, I want to understand the # of clicks my notifications receive (if applicable), which notifications or Events perform the best, the total # notifications I’ve ever shown, and be able to separate date ranges a la Google Analytics. 53 | 54 | 55 | **Aggregate dashboards** 56 | 57 | In the MVP this will be for internal purposes only. The business objective of aggregate User dashboards is to leverage anonymized data to help each individual User 58 | 59 | Examples of insights we could provide: 60 | * What’s the optimal delay (in seconds) between notifications? 61 | * Which font gets the most clicks? 62 | 63 | These insights would be emailed to users in weekly digests (perhaps dynamically) based on their account’s performance (what they see in their dashboard), and provided in-app while Users are using the Queue GUI. 64 | 65 | **Code Examples** 66 | 67 | We can design this similarly to Mixpanel, Yelp, etc. A developer would do the following: 68 | 69 | 1. Authenticate their access to fomo in an initializer, ie config/initializers/fomo.rb. 70 | 71 | ![Fomo Initializer](https://github.com/ryanckulp/feature_spec/raw/master/images/fomo/fomo-initializer.png "Fomo Initializer") 72 | 73 | 2. Instantiate fomo with a friendly identifier, perhaps in a background job. 74 | 75 | ![Fomo Initializer](https://github.com/ryanckulp/feature_spec/raw/master/images/fomo/fomo-instantiate-client.png "Fomo Initializer") 76 | 77 | 3. POST to their Fomo Queue whenever they want. 78 | 79 | Purchase Event (resulting text snippet => “Mike in San Francisco just upgraded to the Awesome plan!”) 80 | 81 | ![Fomo Initializer](https://github.com/ryanckulp/feature_spec/raw/master/images/fomo/fomo-purchase-event.png "Fomo Initializer") 82 | 83 | Signup Event (resulting text snippet => “Ryan from Atlanta is now subscribed to our Tips & Tricks newsletter!”) 84 | 85 | ![Fomo Initializer](https://github.com/ryanckulp/feature_spec/raw/master/images/fomo/fomo-signup-event.png "Fomo Initializer") 86 | 87 | There are many Event types, and we want to provide templates for a few of them. 88 | 89 | This lets us a) understand the types of Events that drive engagement (do Purchase notifications get more clicks than Signup notifications?) as well as b) allow users many different variants of their copy, design, etc showcased on their website. 90 | 91 | 92 | Notice that the copywriting in the above examples is different; one style of merge variables is set to default per event. 93 | 94 | 95 | **WYSIWYG Integrations** 96 | 97 | For non-technical marketers or first-time users who don’t want to implement the API (yet), we should provide a Zapier integration for major Events that many websites encourage. 98 | 99 | 100 | Two examples below, each of which should require no code but simply 1-click integration OR pasting in API keys with instructions to find them. 101 | 102 | 103 | **Signup Event** 104 | 105 | As a marketer, if I use the WYSIWYG Queue admin to manually input a ‘Signup’ event, I should be prompted if I want to connect Mailchimp. Then I can design my font, merge variables, etc as described above (Resources > Wireframes) but have the name or location dynamically provided by Mailchimp. 106 | 107 | 108 | **Purchase Event** 109 | 110 | As a marketer, if I use the WYSIWYG Queue admin to manually input a ‘Signup’ event, I should be prompted if I want to connect my Stripe account. 111 | 112 | 113 | ### Considerations 114 | 115 | Which options do we open up to the API vs require in the Queue GUI. 116 | Such as: font family, css styling, sentence structure, etc. 117 | 118 | 119 | ### Scope 120 | Trim as necessary to achieve MVP in ~45 days. 121 | Offer only an HTTP/CURL + Ruby library in MVP. 122 | 123 | ### Roadmap 124 | 125 | Phase 1 126 | * WYSIWYG Queue admin 127 | * Zapier integration (primary: Mailchimp, Stripe, Google Sheets, etc) 128 | * Single snippet on active web pages, popups work identical to Notify on Shopify (choose a corner, font, etc) 129 | Configuration options (delays, days to show, timestamps, etc) maintained from Notify Admin GUI 130 | 131 | 132 | Phase 2 133 | * API library 134 | * Event types 135 | * Advanced Analytics 136 | -------------------------------------------------------------------------------- /b2c/WhatTimeIsIt.md: -------------------------------------------------------------------------------- 1 | ##Product Spec Related to WhatTimeIsIt.com from Joel Spolsky 2 | 3 | ### Overview 4 | 5 | WhatTimeIsIt.com is a service that tells people what time it is, over the web. 6 | 7 | This spec is not, by any stretch of the imagination, complete. All of the wording will need to be revised several times before it is finalized. The graphics and layout of the screens is shown here merely to illustrate the underlying functionality. The actual look and feel will be developed over time with the input of graphics designers and iterative user feedback. 8 | 9 | This spec does not discuss the algorithms used by the time calculation engine, which will be discussed elsewhere. It simply discusses what the user sees when they interact with WhatTimeIsIt.com. 10 | 11 | ### Scenarios 12 | 13 | In designing products, it helps to imagine a few real life stories of how actual (stereotypical) people would use them. We'll look at two scenarios. 14 | 15 | **Scenario 1: Mike.** 16 | 17 | Mike is a busy executive. He is the president of a large, important company that makes dynamite-based products for children which are sold through national chains such as Toys 'R' Us. During the course of a typical day, he has many meetings with many very important people. Sometimes a man comes over from the bank to harass him for not paying the interest that was due three months ago on his line of credit. Sometimes another man comes from another bank trying to get him to sign up for another line of credit. Sometimes his venture capitalists (the nice people who gave Mike the money to start his business) visit him to complain that he is earning too much money. "A bonfire!" they demand. "Wall Street likes to see a bonfire!" 18 | 19 | These visitors are very upset if Mike has previously promised to meet with them at a certain time, but when that time comes around, Mike is nowhere to be found. This happens because Mike doesn't know what time it is. At his secretary's recommendation, Mike signs up for a WhatTimeIsIt.com account. Now, whenever Mike is wondering about the time, he simply logs onto WhatTimeIsIt.com, enters his username and password, and finds out the current time. He visits the site several times during the day: to find out when it's time for lunch, to check if he's late for the next meeting, etc. Towards the end of the day, in fact, from about 3:00 p.m. onwards, he checks the site increasingly frequently to see when it's time to go home. By 4:45 he's basically just hitting "Refresh" again and again. 20 | 21 | **Scenario 2: Cindy.** 22 | 23 | Cindy is a teenager in high school. She goes to a pretty pathetic public high school, and she's pretty smart, so when she gets home at 2:00 pm, it only takes her about 7 minutes (on average) to do her Algebra homework. None of her other teachers even bother to give her homework. Her baby brother (half brother) is vegged out in front of the only TV set watching Teletubbies, so she spends the afternoon (from 2:07 until about 6:30, when her new mommy serves dinner) surfing the net and chatting with her friends on AOL. She's always looking for exciting new web sites. As a result of typing "What Time Is It?" randomly into a search engine (by mistake, she meant to ask one of her friends using Instant Messenger) she gets to WhatTimeIsIt.com, and sets up a new account. She chooses a user name and "RyanPhillipe" as her password, selects her time zone, and voila -- finds out what time it is. 24 | 25 | ### Non Goals 26 | 27 | This version will not support the following features: 28 | 29 | * multiple time zones for one member. All members are assumed to be in the same time zone. 30 | * changing passwords. 31 | * appointments. 32 | 33 | ### WhatTimeIsIt.com Flowchart 34 | 35 | We'll have time later to go into mind-numbing detail, but for now, let's look at a quick flowchart of the service so you get the big picture. This flowchart is not complete, but it does give you the right idea for the "storyboard" of using WhatTimeIsIt.com: 36 | 37 | ![What Time is It](https://github.com/ryanckulp/feature_spec/raw/master/images/joel_on_software/What_Time_Is_It.gif) 38 | 39 | ### Screen by Screen Specification 40 | 41 | WhatTimeIsIt.com consists of quite a few different screens. Most screens will follow a standard format, with a look and feel to be designed in the future by a graphic designer. This document is more concerned with the functionality and the interaction design, not the exact look and layout. 42 | 43 | All screens are created in HTML. (The single exception is the Splash Screen, which is created using Macromedia Shockwave). 44 | 45 | Each screen in WhatTimeIsIt.com is known by a canonical name which will always appear, in this document, with an underline, so you know we're referring to a screen by name, for example, Home Page. 46 | 47 | ### Splash Screen 48 | 49 | An annoying, gratuitous Shockwave animation that plays stupid music and drives everyone crazy. Splash Screen will be commissioned by a high-paid graphics animation boutique in a loft in Soho from people who bring their dogs to work, wear found objects safety-pinned to their ears, and go to Starbucks four times before lunch. 50 | 51 | After the animation has played for about 10 seconds, a link that says "SKIP THIS" will fade into view in the bottom right corner. To avoid people seeing this and clicking on it, SKIP THIS will be so far down and to the right that most people won't see it. It should be at least 800 pixels from the left border of the animation and 600 pixels from the top. 52 | 53 | Clicking on SKIP THIS goes to Home Page. When the animation is complete, it will redirect the browser to Home Page automatically. 54 | 55 | Open Issue 56 | If Marketing allows, we should deposit a cookie on the user's computer if they click SKIP THIS which will cause the animation to always be skipped in the future. Frequent visitors should not have to see the animation more than once. I talked to Jim in Marketing about this and he's going to take point in convening a committee of Sales, Marketing, and PR to discuss. 57 | 58 | ### Home Page 59 | 60 | Displayed when the Shockwave animation is complete, the Home Page serves three purposes: 61 | 62 | * Allow people to learn about the service and consider whether they want to sign up 63 | * Allow members who have already signed up to log on 64 | * Allow people who want to sign up to create an account. 65 | 66 | The Home Page looks like this: 67 | 68 | ![WhatTimeIsIt.com Home Page](https://github.com/ryanckulp/feature_spec/raw/master/images/joel_on_software/what-time-is-it-home-page.png) 69 | 70 | On this, and on all screens, clicking on the WhatTimeIsIt.com logo in the top left corner goes back to Home Page. 71 | 72 | Technical Note 73 | Because of the high similarity between the various screens, some system of includes should be used on the server so that if the name of the service changes, or if we can't purchase the domain name we want, we'll be able to change all the screens in one place. I suggest Vignette Story Server. Sure, it's overkill. Sure, it costs $200,000. But it's a heck of a lot easier than using server-side includes! 74 | 75 | Clicking on the link that says "click here to log on" goes to Log In Form. Clicking on the link that says "click here to sign up" goes to Sign Up Form. The other five links display pages with static text to be provided by management, which are beyond the scope of this specification. They will not have to change very often. 76 | 77 | ### Log In Form 78 | 79 | The Log In Form is used by current members to log into their accounts in order to find out the current time. It looks like this: 80 | 81 | ![WhatTimeIsIt.com Home Page](https://github.com/ryanckulp/feature_spec/raw/master/images/joel_on_software/what-time-is-it-login-form.png) 82 | 83 | The right side of the screen behaves the same way as described previously under Home Page. 84 | 85 | The email box allows for up to 60 characters to be typed. The password box allows for up to 12 characters to be typed. To disguise them and prevent hacking, as the user types in the password box, asterisks (*) will appear instead of the characters that they type. 86 | 87 | **Technical Note** 88 | This is accomplished using 89 | 90 | When the user clicks Log In, the following checks are performed on the server: 91 | 92 | 1. If the email address was provided, but it could not be a real email address because it is not formatted correctly (e.g. there is no @ sign or it contains characters that are not permitted in email addresses by RFC-822), the server returns another page that looks just like Log In Form, only this time, a red error message is inserted above the address box, saying "The email address you provided is not valid. Please double check it." Although this text is in red, the text "Please enter your email address" still appears in black. The incorrect email address that the user originally typed will now be pre-populated in the edit box. 93 | 94 | 2. If the email address was provided, but it does not correspond to a registered member, the server returns another page that looks just like Log In Form, only this time, a red error message is inserted above the address box, saying "The email address you provided is not a member. Please double check it. To become a member, click on the link on the right side of the screen." Although this text is in red, the text "Please enter your email address" still appears in black. The incorrect email address that the user originally typed will now be pre-populated in the edit box. [ Question to developers. Can we use JavaScript in this case so that if the user then clicks on the link to become a member, we automatically pre-populate the email address on the sign up form? ] 95 | 96 | 3. If the email address was provided, and it does correspond to a registered member, but no password was typed at all, we send an email to that address containing the password. The subject of the email is "Your WhatTimeIsIt.com membership". The email is in plain text. The exact wording of this email is still being debated hotly by the board of directors and will be provided sometime before shipping. [ Developers: for now I suggest using a nasty word. That will light a fire under Chucks' seat. ] 97 | 98 | 4. If the email address was provided, and it does correspond to a registered member, and a password was provided, but the password is incorrect, the server returns another page that looks just like Log In Form, only this time, a red error message is inserted above the password box, saying "The password you provided is not valid. Please double check it. Remember, passwords are case-sensitive." If the password typed does not contain any lower case alphabetic characters, we add this text to the message: "Perhaps you've accidentally turned on CAPS LOCK?" Whenever the password is incorrect, the Log In Form comes back with the password box clear. 99 | 100 | 5. If the email address and password are OK, jump straight to Display Time. 101 | 102 | **Open Issue** 103 | Need to decide about JavaScript in case #2 104 | 105 | **Open Issue** 106 | Need wording for password email from CEO 107 | --------------------------------------------------------------------------------