A guide to writing specs toward engineers

This slide is for Product Managers who want to write specs that can get buy-in from engineers and is well stated that a team cans start working on it without hassle.

Transcript

1. A guide to writing specs toward engineers Tomoaki Imai
2. HOW GOOD FRIENDS FOOD Goal • Write specs that help communicate smoothly with engineers • Write easy to read, simple to get up to speed on specs for your team • Not too descriptive(no 10 page documents) • Precise explanations • Out of scope • Specs for other stakeholders(designers, marketers) 2
3. HOW GOOD FRIENDS FOOD What do engineers expect for specs
4. HOW GOOD FRIENDS FOOD What do engineers expect for specs 1.Why you want to work on this is crystal clear 2.What you propose is explicit 3.KISS(Keep It Short and Simple) 
 4
5. HOW GOOD FRIENDS FOOD 1. Why you want to work on this is crystal clear • This is important for engineers to get motivated • What is your hypothesis? • How would this feature affect the product and users? 5 Feature: Friend Request by Facebook/Contact list Problem Statement - Over x% of users stop using our app when they don’t have friends to share his/her photos Hypothesis - User who has friends would probably keep using our service - Having various channels(etc FB, contact list) would improve the friend request rate Effect - Currently User can only search friends by name. With this feature, User can easily find friends from the service. - # of friends per User should increase. This feature will impact Q1’s Key Result XXXX
6. HOW GOOD FRIENDS FOOD 2. What you propose is explicit • Acceptance Criteria • What output do you expect - Ex. User should be able to create an account • This is not the place to explain the details • Scope/Out of Scope and Priority • Target User & Effected screens • What is NOT addressed in this Specs • What is the minimum requirement for initial launch • When do you want to release this feature by? 6 Acceptance Criteria - User can send/accept Friend Requests - User can give access to FB/Contact list and look for friends who is using the service Scope - Target User: new users who has less than 2 friends - Effected Screens - Conversation List Screen - Add Friend screen Out of Scope - Sending friend requests using external apps(invitation) Schedule - 2 weeks later, before Q2 starts Minimum requirement - Friend request to Facebook friend who is using this service
7. HOW GOOD FRIENDS FOOD 3. KISS(Keep it Simple and Short) • Engineers can't understand what is important in your spec if the document is too long • Don't need to describe what the design covers • Explain what the user journey would look like • Timeline of the user behavior • Describe actions on each touch point 7
8. HOW GOOD FRIENDS FOOD Required on Specs • Navigation/Interaction of each components/screen • What happens when a button is tapped? • Where does this screen transition to? • Life cycle of this feature • How many times do you want to show the Alert? • How long do you want to keep this data? • Edge cases • What will happen if the action failed? • Non-functional requirement (if any for this specific use case) • Ex1. Respond within 1 sec, do not show loading • Ex2. Validation should run before posting on the client side 8 When Add is tapped, the card will disappear Screen slides up When “Add” is tapped, request will be sent and the button switches to “Pending” Once closed, it won’t show up again in this screen The order depends on how close this user is; - # of mutual friends - From Facebook user
9. HOW GOOD FRIENDS FOOD Not Required on Specs • UI spec; something obvious on the design • How to implement (that’s on engineers) • Ambiguity • Something unclear to engineers as to whether it should be implemented or not • Leave it as a side note if you think it’s important 9
10. HOW GOOD FRIENDS FOOD Miscellaneous topics about specs
11. HOW GOOD FRIENDS FOOD When to start writing Specs • The sooner the better • 1 week in advance for medium features, 2 weeks or more for large features • Start from a draft and ask for reviews • This will also help you get buy-in from engineers 11 - Draft - Mock Design - Review/Feedbacks - Brainstorming - Detail - Brushed up Design - Schedule - Q&A session - Ready to develop
12. HOW GOOD FRIENDS FOOD Feedback • Do not consider it as an attack • Engineers just want to clarify the spec • Engineers want to expose your hidden requirements • Engineers want to suggest their ideas to achieve the objective • You can listen, but you don’t have to follow • If you believe the specs you defined are better, keep them as is 12
13. HOW GOOD FRIENDS FOOD Misc • What if you are not sure if it can be done? • Talk to engineers first and get some idea (again, don’t leave ambiguity on specs!) • Creating an investigation task in advance would help reduce uncertainity • What if you want to update the spec afterward? • Make the change explicit (underline, leave a note, add the date you updated) • Let engineers know about the change. Avoid miscommunication! 13