Lazy Programmer's Guide To Writing Spec

Techniques for capturing business requirements. This is a guide for software developer to help them get started on writing specifications. This is presented at Inno Tech Bootcamp 2 on 5th July 2018. #itbc2

Keywords: flowchart, diagrams, business process, sequence diagram, module diagram, analysis.

Transcript

1. Lazy Programmer’s Guide To Writing Spec Inno Tech Boot Camp 2018 July #ITBC2 Leong Hean Hong
2. Agenda • Purpose • Feature List • Business Process • Business Rule • Other Diagrams • API Spec
4. Why Should I Write Spec? • Confirm what user wants • Make sure we are developing the right software • Clarity among team members • Ensure members work toward same direction Tip: Do not write something nobody reads
5. Guideline • Start from high level, go more detail as you need • If not sure need to write or not, write anywhere • Be as specific as possible • Prefer image over words • Make it easy to read & understand • Assume reader of spec document is confused, with no prior knowledge of this project
6. Let’s build an eWallet!
7. Feature List
9. Functional vs Nonfunctional Requirements • Functional Requirements - that is of value to user • Nonfunctional Requirements - user don’t care
10. Functional Requirements • An user can transfer money to another user • User can topup wallet using different payment methods (Credit Card, IB, scratch card) • User can check balance • User can receive money by sending URL link to payer • User can transfer money by scanning QR code
11. Nonfunctional Requirements • Network communication must be secured (HTTPS) • Compliance with KYC, AML/CFT • It need to support at least 200 concurrent transactions • Log all transactions • Daily reconcile
12. Business Processes
14. Business Process • Sequence of actions user performs to achieve an objective. • User can be human or system • Example of objective ◦ Scan QR code to make payment ◦ Generate and send payment link • Method ◦ Writing ◦ Flowchart ◦ Sequence Diagram
15. Example: Writing 1. Merchant use system to generate QR code. 2. Merchant print and display QR code. 3. Payer scan QR code. 4. Payer types in payment amount. 5. Payer confirms payment with 6-digits PIN.
16. Method: Writing • Clearly define actors (“who”) and actions (“what”) • Hard to express if/else, loop • Wordy
17. Example: Flowchart
18. Method: Flowchart • Can express if/else, loop • Take up large space • Flow chart symbols: http://bit.ly/2zanyxb ◦ Start/end ◦ Process ◦ Display ◦ Decision • Lack of actor information
19. Example: Sequence Diagram
20. Method: Sequence Diagram • Clearly define actors and actions • Hard to express if/else, loop • Shows interactions between multiple actors • Sequence from top to bottom
21. Business Rules
23. Business Rules • Imagine “if/else” and “switch” for business. • Make decision based on conditions/criteria
24. Business Rule Example (1) Amount < $50.00 Amount ≥ $50.00 ID Verified Y Y ID Not Yet Verified Y N Rules for allowing transfer:
25. Business Rule Example (2) Topup Amount Reward < $50 1% $50.00 ~ $99.99 2% $100.00 ~ $199.99 3% ≥ $200.00 4%
26. Other Diagrams
27. System Diagram
28. System Diagram • High-level concept • Relationship between different (sub)systems
29. Module Diagram
30. Module Diagram • Dependency: top depend on bottom • Composition: module contain submodules
31. Relationship Diagram
32. Relationship Diagram • Different from entity-relationship diagram • Good for showing high-level concepts • Describes relationships • May not be direct reflection of DB schema
33. API Spec
34. API Spec • Test/Production URLs • Authentication (e.g. Token, HTTP Basic Auth) • Listing of each endpoint ◦ Brief description ◦ List all parameter (name, data type, optional?, description, data size, values) ◦ Example request ◦ Example response Reference: • Xpressify, Mailgun
35. Ending Note • Inspired by UML Diagrams (highly recommend you read up on it http://bfy.tw/5dZO) ◦ Class Diagram ◦ Activity Diagram ◦ Sequence Diagram ◦ State Machine Diagram