├── README.md ├── tdd-workshop ├── templates │ ├── simple.md │ ├── discovery.md │ ├── step-by-step.md │ ├── phased.md │ ├── practical.md │ ├── google.md │ ├── simple-example.md │ ├── extended.md │ ├── practical-example.md │ └── comprehensive.md ├── about.md ├── presentation.md └── index.html └── portfolio └── about.md /README.md: -------------------------------------------------------------------------------- 1 | # Christy La Guardia's Tech Talks 2 | 3 | 1. [Technical Design Document Workshop](/tdd-workshop/about.md) 4 | 2. [Creating Portfolios for Engineers](/portfolio/about.md) 5 | -------------------------------------------------------------------------------- /tdd-workshop/templates/simple.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Project Name TDD 4 | 5 | Author: ? 6 | 7 | ## What are you building? 8 | 9 | 10 | 11 | ? 12 | 13 | ## How are you going to build it? 14 | 15 | 16 | 17 | ? 18 | 19 | ## Why are you building it that way? 20 | 21 | 22 | 23 | ? 24 | -------------------------------------------------------------------------------- /tdd-workshop/templates/discovery.md: -------------------------------------------------------------------------------- 1 | 2 | # Project Name Discovery 3 | 4 | Author: ? 5 | 6 | ## Context 7 | 8 | 9 | 10 | ? 11 | 12 | ## Summary of Results 13 | 14 | 15 | 16 | ? 17 | 18 | ## Focus Area? 19 | 20 | 21 | 22 | ? 23 | 24 | ## Focus Area? 25 | 26 | 27 | 28 | ? 29 | 30 | ## Focus Area? 31 | 32 | 33 | 34 | ? 35 | 36 | ## Proposed Work 37 | 38 | ? 39 | -------------------------------------------------------------------------------- /tdd-workshop/templates/step-by-step.md: -------------------------------------------------------------------------------- 1 | 2 | # Project Name TDD 3 | 4 | Author: ? 5 | 6 | ## Overview 7 | 8 | 9 | 10 | ? 11 | 12 | ## Assumptions 13 | 14 | 15 | 16 | ? 17 | 18 | ## Step 1: ? 19 | 20 | ### Work 21 | 22 | 23 | 24 | 1. ? 25 | 2. ? 26 | 3. ? 27 | 28 | ### Criteria 29 | 30 | 31 | 32 | 1. ? 33 | 2. ? 34 | 3. ? 35 | 36 | ## Step 2: ? 37 | 38 | ### Work 39 | 40 | 41 | 42 | 1. ? 43 | 2. ? 44 | 3. ? 45 | 46 | ### Criteria 47 | 48 | 49 | 50 | 1. ? 51 | 2. ? 52 | 3. ? 53 | 54 | ## Step ?: ? 55 | 56 | ### Work 57 | 58 | 59 | 60 | 1. ? 61 | 2. ? 62 | 3. ? 63 | 64 | ### Criteria 65 | 66 | 67 | 68 | 1. ? 69 | 2. ? 70 | 3. ? 71 | 72 | ## Questions 73 | 74 | 1. ? 75 | 2. ? 76 | 3. ? 77 | -------------------------------------------------------------------------------- /tdd-workshop/templates/phased.md: -------------------------------------------------------------------------------- 1 | 2 | # Project Name TDD 3 | 4 | Author: ? 5 | 6 | # Introduction 7 | 8 | ## Problem Statement 9 | 10 | 11 | 12 | ? 13 | 14 | ## Problem Solution 15 | 16 | 17 | 18 | ? 19 | 20 | ## Phase 1 21 | 22 | ### LOE 23 | 24 | 25 | 26 | ? 27 | 28 | ### Goals / Non-Goals 29 | 30 | 31 | 32 | ? 33 | 34 | ### Considerations 35 | 36 | 43 | 44 | #### User Interface? 45 | 46 | ? 47 | 48 | #### Data Model? 49 | 50 | ? 51 | 52 | #### API Endpoints? 53 | 54 | ? 55 | 56 | #### Business Logic? 57 | 58 | ? 59 | 60 | #### Testing? 61 | 62 | ? 63 | 64 | #### Risks? 65 | 66 | ? 67 | 68 | #### Documentation? 69 | 70 | ? 71 | 72 | #### Open Questions? 73 | 74 | ? 75 | 76 | #### Alternative Solutions? 77 | 78 | ? 79 | 80 | ## Phase 2 81 | 82 | 83 | 84 | ? 85 | 86 | ## Phase ? 87 | 88 | 89 | 90 | ? 91 | 92 | ## Future Work 93 | 94 | ? 95 | -------------------------------------------------------------------------------- /tdd-workshop/templates/practical.md: -------------------------------------------------------------------------------- 1 | 5 | 6 | # Project Name TDD 7 | 8 | ## Problem 9 | 10 | 11 | 12 | ? 13 | 14 | ## Background 15 | 16 | 17 | 18 | ? 19 | 20 | ## Goals 21 | 22 | 23 | 24 | ? 25 | 26 | ## Non-Goals 27 | 28 | 29 | 30 | ? 31 | 32 | ## Design Options 33 | 34 | 35 | 36 | ### Option 1: ? 37 | 38 | ? 39 | 40 | Pros: 41 | 42 | 1. ? 43 | 44 | Cons: 45 | 46 | 1. ? 47 | 48 | ### Option 2: ? 49 | 50 | ? 51 | 52 | Pros: 53 | 54 | 1. ? 55 | 56 | Cons: 57 | 58 | 1. ? 59 | 60 | ### Option 3: ? 61 | 62 | ? 63 | 64 | Pros: 65 | 66 | 1. ? 67 | 68 | Cons: 69 | 70 | 1. ? 71 | 72 | #### Conclusion 73 | 74 | 75 | 76 | ? 77 | -------------------------------------------------------------------------------- /tdd-workshop/templates/google.md: -------------------------------------------------------------------------------- 1 | 5 | 6 | # Project Name TDD 7 | 8 | Author: ? 9 | 10 | ## Context and Scope 11 | 12 | 13 | 14 | ? 15 | 16 | ## Goals and Non-Goals 17 | 18 | 19 | 20 | ? 21 | 22 | ## Design 23 | 24 | 29 | 30 | ### Overview 31 | 32 | ? 33 | 34 | ### Topics 35 | 36 | #### System-context-diagram 37 | 38 | 39 | 40 | ? 41 | 42 | #### APIs 43 | 44 | 45 | 46 | ? 47 | 48 | #### Data storage 49 | 50 | 51 | 52 | ? 53 | 54 | #### Code and pseudo-code 55 | 56 | 57 | 58 | ? 59 | 60 | ## Alternatives Considered 61 | 62 | 63 | 64 | ? 65 | 66 | ## Cross-cutting concerns 67 | 68 | 69 | 70 | ? 71 | -------------------------------------------------------------------------------- /tdd-workshop/templates/simple-example.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Project Name TDD 4 | 5 | Author: ? 6 | 7 | ## What are you building? 8 | 9 | 10 | 11 | I really like to cook, but I'm also very disorganized. I'd like to have a better way to read my recipes. 12 | 13 | I will create a simple website for viewing my recipes. 14 | 15 | ## How are you going to build it? 16 | 17 | 18 | 19 | I'd like to use the Jamstack for this, which includes: 20 | 21 | 1. Pre-rendering static html with a popular framework like Gatsby, Hugo or NextJS. See [this guide](https://jamstack.org/generators/). 22 | 2. For the MVP, I won't and any special JS or any external APIs. 23 | 3. The data itself could be hardcoded JSON files for now. 24 | 4. Eventually, I might want save the content in a database or use a Content Management Systems (CMS) like Contentful. 25 | 5. I'd like to de-scope complex deployments right now, and just something simple like GitHub pages. 26 | 27 | ## Why are you building it that way? 28 | 29 | 30 | 31 | Given the high volume of cooking I do, I need a site that will load fast. Static pages are very fast. 32 | 33 | I could skip the framework and just write the recipes in regular HTML files, but I'd like to avoid future time consuming work from moving the recipes from html to a database or CMS. 34 | -------------------------------------------------------------------------------- /tdd-workshop/templates/extended.md: -------------------------------------------------------------------------------- 1 | 2 | # Project Name TDD 3 | 4 | Author: Your Name 5 | 6 | ## Context 7 | 8 | ### Problem Statement 9 | 10 | 11 | 12 | ? 13 | 14 | ### Problem Solution 15 | 16 | 17 | 18 | ? 19 | 20 | ## Design 21 | 22 | ### Overview 23 | 24 | 25 | 26 | ### Details 27 | 28 | #### User Interface 29 | 30 | 31 | 32 | ? 33 | 34 | #### Data Storage 35 | 36 | 37 | 38 | ? 39 | 40 | #### APIs 41 | 42 | 43 | 44 | ? 45 | 46 | #### Dependencies 47 | 48 | 49 | 50 | ? 51 | 52 | ### Testing 53 | 54 | 55 | 56 | ? 57 | 58 | ### Documentation 59 | 60 | 61 | 62 | ? 63 | 64 | ### Release 65 | 66 | 67 | 68 | ? 69 | -------------------------------------------------------------------------------- /portfolio/about.md: -------------------------------------------------------------------------------- 1 | # Creating Portfolios for Engineers 2 | 3 | _Watch my talk at [Women Who Code CONNECT Recharge 2022](https://hopin.com/events/connect-recharge-2022/registration)!_ 4 | 5 | I rebuilt [my portfolio site](https://christylaguardia.com/projects) over a dozen times! Why? Because I didn’t know what to avoid when creating one! If you’re in job hunting mode a well-crafted portfolio could help you stand out. In this talk, I’ll show all the mistakes I made and how you can avoid them. 6 | 7 | ## Avoid these mistakes I made 8 | 9 | 1. Spending way too much time on it. 10 | 2. Building it from scratch. 11 | 3. Selecting the wrong portfolio pieces. 12 | 4. Having an unclear presentation of them. 13 | 5. Over and under designing my portfolio. 14 | 6. Don’t bury your contact info. 15 | 7. Not sharing it! 16 | 17 | ## Resources 18 | 19 | ### Alternatives & templates 20 | 21 | * [About.me](https://about.me/) 22 | * [Portfoliobox](https://www.portfoliobox.net/) 23 | * [Webflow Templates](https://webflow.com/tag/portfolio-websites) 24 | * [Squarespace Templates](https://www.squarespace.com/websites/create-a-portfolio) 25 | * [Awesome Github Pages Portfolio Templates](https://github.com/guilyx/awesome-github-pages-portfolios) 26 | * [Best Portfolio websites builders by fernandocomet](https://uxplanet.org/best-portfolio-websites-builders-4d0900d1a78f) 27 | 28 | ### Articles 29 | 30 | #### Getting started 31 | 32 | * [How to Create a Portfolio Website – A Beginner Developer's Guide by Jemima Abu](https://www.freecodecamp.org/news/beginners-guide-to-creating-a-portfolio-website/) 33 | * [How to Build Portfolio Website And Host It on GitHub Pages? by Chandrika Deb](https://www.geeksforgeeks.org/how-to-build-portfolio-website-and-host-it-on-github-pages/) 34 | * [Using GitHub to Build a Portfolio (2022 Ultimate Guide) by Justin Skiles](https://yourbrainoncomputers.com/using-github-to-build-a-portfolio-ultimate-guide/) 35 | 36 | #### GitHub Profile README 37 | 38 | * [How to Create an Impressive GitHub Profile README by Nida Khan](https://www.sitepoint.com/github-profile-readme/) 39 | * [How to enable GitHub Actions on your Profile README for a snake-eating contribution graph by Michelle Mannering](https://dev.to/mishmanners/how-to-enable-github-actions-on-your-profile-readme-for-a-contribution-graph-4l66) 40 | * [[Docs]Managing your profile README](https://docs.github.com/en/account-and-profile/setting-up-and-managing-your-github-profile/customizing-your-profile/managing-your-profile-readme) 41 | * [Badges 4 README.md Profile by Alexandre Sanlim](https://github.com/alexandresanlim/Badges4-README.md-Profile) 42 | 43 | #### Read this before building 44 | 45 | * [Don't waste your time on a (React) portfolio website by Johannes Kettmann](https://profy.dev/article/portfolio-websites-survey) 46 | 47 | #### Noteworthy considerations 48 | 49 | * [12 Things Web Developers Must Include in Their Portfolios by Laurence Bradford](https://www.codementor.io/learn-programming/12-important-things-to-include-in-web-dev-portfolios) 50 | 51 | #### For freelancers 52 | 53 | * [How to make an online portfolio that will impress clients by Jeff Cardello and Rease Kirchner](https://webflow.com/blog/how-to-make-an-online-portfolio) 54 | 55 | #### Other 56 | 57 | * [How I Built My Design Portfolio from Scratch by Jingyi Lai](https://blog.prototypr.io/how-i-built-my-design-portfolio-from-scratch-c9a44ec079a5) 58 | 59 | ### Curated lists of portfolios 60 | 61 | * :point_right: [Developer Portfolios](https://github.com/emmabostian/developer-portfolios) :point_left: 62 | * [Awesome Creative Portfolio Websites](https://github.com/amnashanwar/awesome-portfolios) 63 | * [Creative Portfolios](https://github.com/iRaul/creative-portfolios) 64 | * [Awesome Portfolios](https://github.com/JonathanMH/all-the-awesome-portfolios) 65 | * [Awesome Portfolio Websites](https://github.com/smaranjitghose/awesome-portfolio-websites) 66 | * [25 Inspiring Web Designer & Developer Portfolios For 2022 by Steve Benjamins](https://www.sitebuilderreport.com/inspiration/web-developer-designer-portfolios) 67 | 68 | #### My favorites 69 | 70 | * [Martin Gauer](https://martingauer.com/) 71 | * [David Calle](https://davidcalle.webflow.io/) 72 | * [Eva Habermann](https://www.eva-habermann.com/) 73 | * [Joshua Kaplan](https://www.joshuakaplan.com/) 74 | * [Nicholas Chiang](https://nicholaschiang.com/) 75 | * [Ryan Dahl](https://tinyclouds.org/) 76 | * [Scott Harlan](https://scottharlan.dev/) 77 | * [Taylor Callan Williams](https://taylorcallanwilliams.netlify.app/) 78 | -------------------------------------------------------------------------------- /tdd-workshop/templates/practical-example.md: -------------------------------------------------------------------------------- 1 | 5 | 6 | # Speech-to-Text App TDD 7 | 8 | ## Problem 9 | 10 | 11 | 12 | We would like to design a Speech-to-Text app for Android devices. A user can tap on a button on the app, and the transcript will show up on the screen as the user speaks. 13 | 14 | ## Background 15 | 16 | 17 | 18 | According to recent research and interviews with Patent Attorneys, we noticed there is an increasing need to auto dictate while interviewing their clients. Patent Attorneys also needs to review the original voice recordings if the transcript is not accurate. 19 | 20 | ## Goals 21 | 22 | 23 | 24 | 1. The transcribing accuracy rate can have 90% and higher. 25 | 2. The speech binary data can be captured and stored for future auditing. 26 | 3. Keep the size of the Android APK under 100 MB. 27 | 4. The transcribing process should be continuous, meaning that the user can see the transcripts while the user is talking. 28 | 29 | ## Non-Goals 30 | 31 | 32 | 33 | 1. Build the speech data auditing process. Reason: we will decide on how to build this later. Currently, we need to preserve user info and speech data. 34 | 35 | ## Design Options 36 | 37 | 38 | 39 | ### Option 1: The app calls a cloud-based Automatic Speech Recognition (ASR) service directly 40 | 41 | We could use a 3rd party cloud service (such as Amazon Autotranscribe, Google Speech-to-Text) directly. The Android app can make requests to the ASR service directly, and display the response to the screen immediately. 42 | 43 | Pros: 44 | 45 | 1. By now, a mature ASR service such as Amazon Transcribe is able to provide 95% and over transcribing accuracy. (This meets Goal #1) 46 | 2. No need to set up a server. 47 | 48 | Cons: 49 | 50 | 1. The speech binary data cannot be captured. (This is against Goal #2) 51 | 2. The 3rd party ASR service is not free. 52 | 53 | ### Option 2: Build the pre-trained embedded ASR in the App 54 | 55 | Pros: 56 | 57 | Cons: 58 | 59 | ### Option 3: A HTTP/1.1 service makes proxy calls to a cloud-based Automatic Speech Recognition (ASR) service 60 | 61 | We could set up a proxy service between the Android app and a 3rd party cloud service (such as Amazon Autotranscribe, Google Speech-to-Text). When the user taps the button, the speech binary data is recorded on the app and sends it to the proxy service. As the proxy service pipes the data to the ASR service, it can also grab the data and store it elsewhere (For example, Google Storage). 62 | 63 | Pros: 64 | 65 | 1. Google Speech-to-Text service can provide 95% transcribing accuracy. (This meets Goal #1) 66 | 2. The speech binary data can be captured and stored. (This meets Goal #2) 67 | 3. The Android app would be a thin client without doing transcribing itself. The size of the app cannot increase significantly. (This meets Goal #3) 68 | 69 | Cons: 70 | 71 | 1. An additional service needs to be set up. However, it is very easy to set up a service with HTTP/1.1. 72 | 2. The transcribing process would not be continuous because of the one-directional nature of the HTTP/1.1 service. (This is against Goal #4) 73 | 74 | ### Option 4: A bidirectional RPC service to proxy calls to a cloud-based ASR service 75 | 76 | ![Option 4](https://miro.medium.com/max/1344/1*07iudFxdWXm_gDGNuwv9kw.jpeg) 77 | 78 | **Pros** 79 | 80 | Cons: 81 | 82 | #### Conclusion 83 | 84 | 85 | 86 | Based on the analysis above, the proposed approach is Option 4, which meets all the Goals. 87 | -------------------------------------------------------------------------------- /tdd-workshop/about.md: -------------------------------------------------------------------------------- 1 | # Technical Design Document Workshop 2 | 3 | This is a workshop designed to teach beginners how to write a Technical Design Document (TDD). 4 | 5 |
6 | About 7 | I'm a Senior Software Engineer at ClassPass and an Alchemy Code Lab graduate (2017). One of the biggest challenges I faced as a new engineer was learning how to pause before coding, plan my work and collaborate with my co-workers. 8 | 9 | Since there aren't any hard-set industry standards for designing software, nor could there be, a common practice is to create a technical document explaining your how you plan to tackle your project. 10 | 11 | Writing TDDs is a skill, and takes practice. It's my belief that starting early in your career will help you learn, grow and advance. 12 | 13 | In this workshop, I'll go over the basics. I'll show you how know when you need a TDD and how to think through your design. I'll share with you some examples and templates for all levels of complexity and difficulty. 14 | 15 | Feel free to contact me at christinelaguardia@gmail.com or connect on [LinkedIn](https://www.linkedin.com/in/christy-la-guardia). 16 |
17 | 18 |
19 | Presentation 20 | View the slides: https://christylaguardia.github.io/tdd-workshop/ 21 | 22 | The presentation is written in markdown and converted to html using [Marp](https://marp.app/). See the [Marp docs](https://marpit.marp.app/markdown) for markdown syntax. 23 | 24 | To convert the md to html: 25 | 26 | 1. Install the [marp-cli](https://github.com/marp-team/marp-cli) with `brew install marp-cli`. 27 | 28 | ```bash 29 | brew install marp-cli 30 | ``` 31 | 32 | 2. Convert markdown to html 33 | 34 | ```bash 35 | marp presentation.md -o index.html 36 | ``` 37 |
38 | 39 | ## Workshop Instructions 40 | 41 | Working individually or in pairs, practice writing a TDD! 42 | 43 | 1. **Choose a project to use as the subject of your TDD.** 44 | 45 | Don’t spend a long time deciding what this is. The project itself isn’t *that* important for this exercise, so it doesn’t need to be unique or special. If you're not sure, start with something simple. It can be a project you’ve already completed or you can come up with an idea. 46 | 47 | 2. **Select a template.** 48 | 49 | Start with one of the sample templates, in order of complexity + difficulty: 50 | 51 | 1. [simple](templates/simple.md) 52 | 2. [practical](templates/practical.md) 53 | 3. [extended](templates/extended.md) 54 | 4. [step-by-step](templates/step-by-step.md) 55 | 5. [phased](templates/phased.md) 56 | 6. [google](templates/google.md) 57 | 7. [comprehensive](templates/comprehensive.md) 58 | 59 | Each template has sections with guidelines on what to write in that section in the comments ``. 60 | 61 | If none of the templates seem right for your project, feel free to copy one and modify the sections, or create your own. 62 | 63 | 3. **Write your TDD** 64 | 65 | Create a branch. Make a copy of your selected template in the [workshop](/workshop) folder. Work through each section of the template, reading the guidelines comments and writing as you go. Remember, don't overthink everything, write what you know, call out what you don't know. 66 | 67 | 4. **Create a PR** 68 | 69 | Submit your TDD for peer-review by creating a pull request. 70 | 71 | 5. **Review other TDDs** 72 | 73 | Find a pull request that needs review. Read through the TDD. Ask questions or leave comments by submitting a [review](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/about-pull-request-reviews). 74 | 75 | When reviewing someone's TDD, conider: 76 | 77 | - Do you understand the context? 78 | - Can you follow the design or implementation details? 79 | - Is complexity and difficultly explained? 80 | - Are there areas that could use some more explanation or details? 81 | - Questions you might have? 82 | 83 | ## Markdown Tips 84 | 85 | 1. Skip VS Code, and write and commit your markdown directly in GitHub. 86 | 2. Write nicely formatted markdown with the [markdownlint](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint) and the [Code Spell Checker](https://marketplace.visualstudio.com/items?itemName=streetsidesoftware.code-spell-checker) extensions for VS Code. 87 | 88 | ## Resources 89 | 90 | - [A Practical Guide to Writing a Software Technical Design Document (by Grace Huang)](https://medium.com/swlh/a-practical-guide-to-writing-a-software-technical-design-document-c6f4d865ccff) 91 | - [A practical guide to writing technical specs (by Zara Cooper, Stackoverflow)](https://stackoverflow.blog/2020/04/06/a-practical-guide-to-writing-technical-specs/) 92 | - [Design Docs at Google (by Malte Ubl, Industrial Empathy)](https://www.industrialempathy.com/posts/design-docs-at-google/) 93 | - [Technical Design (Stanford IT)](https://uit.stanford.edu/pmo/technical-design) 94 | - [Why Tech Specification is Important? (by Slava Podmurnyi, Visartech)](https://www.visartech.com/blog/10-reasons-why-you-should-write-technical-specification/) 95 | - [Writing Technical Design Docs (by Talin, Engineering Insights)](https://medium.com/machine-words/writing-technical-design-docs-71f446e42f2e) 96 | -------------------------------------------------------------------------------- /tdd-workshop/templates/comprehensive.md: -------------------------------------------------------------------------------- 1 | 5 | # Project Name TDD 6 | 7 | ## 1. Front matter 8 | 9 | - *Author(s)* 10 | - *Team* 11 | - *Reviewer(s)* 12 | - *Created on* 13 | - *Last updated* 14 | - *Epic, ticket, issue, or task tracker reference link* 15 | 16 | ## 2. Introduction 17 | 18 | ### a. Overview, Problem Description, Summary, or Abstract 19 | 20 | - *Summary of the problem (from the perspective of the user), the context, suggested solution, and the stakeholders.* 21 | 22 | ### b. Glossary or Terminology 23 | 24 | - *New terms you come across as you research your design or terms you may suspect your readers/stakeholders not to know.* 25 | 26 | ### c. Context or Background 27 | 28 | - *Reasons why the problem is worth solving* 29 | - *Origin of the problem* 30 | - *How the problem affects users and company goals* 31 | - *Past efforts made to solve the solution and why they were not effective* 32 | - *How the product relates to team goals, OKRs* 33 | - *How the solution fits into the overall product roadmap and strategy* 34 | - *How the solution fits into the technical strategy* 35 | 36 | ### d. Goals or Product and Technical Requirements 37 | 38 | - *Product requirements in the form of user stories* 39 | - *Technical requirements* 40 | 41 | ### e. Non-Goals or Out of Scope 42 | 43 | - *Product and technical requirements that will be disregarded* 44 | 45 | ### f. Future Goals 46 | 47 | - *Product and technical requirements slated for a future time* 48 | 49 | ### g. Assumptions 50 | 51 | - *Conditions and resources that need to be present and accessible for the solution to work as described.* 52 | 53 | ## 3. Solutions 54 | 55 | ### a. Current or Existing Solution / Design 56 | 57 | - *Current solution description* 58 | - *Pros and cons of the current solution* 59 | 60 | ### b. Suggested or Proposed Solution / Design 61 | 62 | - *External components that the solution will interact with and that it will alter* 63 | - *Dependencies of the current solution* 64 | - *Pros and cons of the proposed solution* 65 | - *Data Model / Schema Changes* 66 | - *Schema definitions* 67 | - *New data models* 68 | - *Modified data models* 69 | - *Data validation methods* 70 | - *Business Logic* 71 | - *API changes* 72 | - *Pseudocode* 73 | - *Flowcharts* 74 | - *Error states* 75 | - *Failure scenarios* 76 | - *Conditions that lead to errors and failures* 77 | - *Limitations* 78 | - *Presentation Layer* 79 | - *User requirements* 80 | - *UX changes* 81 | - *UI changes* 82 | - *Wireframes with descriptions* 83 | - *Links to UI/UX designer’s work* 84 | - *Mobile concerns* 85 | - *Web concerns* 86 | - *UI states* 87 | - *Error handling* 88 | - *Other questions to answer* 89 | - *How will the solution scale?* 90 | - *What are the limitations of the solution?* 91 | - *How will it recover in the event of a failure?* 92 | - *How will it cope with future requirements?* 93 | 94 | ### c. Test Plan 95 | 96 | - *Explanations of how the tests will make sure user requirements are met* 97 | - *Unit tests* 98 | - *Integrations tests* 99 | - *QA* 100 | 101 | ### d. Monitoring and Alerting Plan 102 | 103 | - *Logging plan and tools* 104 | - *Monitoring plan and tools* 105 | - *Metrics to be used to measure health* 106 | - *How to ensure observability* 107 | - *Alerting plan and tools* 108 | 109 | ### e. Release / Roll-out and Deployment Plan 110 | 111 | - *Deployment architecture* 112 | - *Deployment environments* 113 | - *Phased roll-out plan e.g. using feature flags* 114 | - *Plan outlining how to communicate changes to the users, for example, with release notes* 115 | 116 | ### f. Rollback Plan 117 | 118 | - *Detailed and specific liabilities* 119 | - *Plan to reduce liabilities* 120 | - *Plan describing how to prevent other components, services, and systems from being affected* 121 | 122 | ### g. Alternate Solutions / Designs* 123 | 124 | - *Short summary statement for each alternative solution* 125 | - *Pros and cons for each alternative* 126 | - *Reasons why each solution couldn’t work * 127 | - *Ways in which alternatives were inferior to the proposed solution* 128 | - *Migration plan to next best alternative in case the proposed solution falls through* 129 | 130 | ## 4. Further Considerations 131 | 132 | ### a. Impact on other teams 133 | 134 | - *How will this increase the work of other people?* 135 | - *b. Third-party services and platforms considerations* 136 | 137 | - *Is it really worth it compared to building the service in-house?* 138 | - *What are some of the security and privacy concerns associated with the services/platforms?* 139 | - *How much will it cost?* 140 | - *How will it scale?* 141 | - *What possible future issues are anticipated?* 142 | 143 | ### c. Cost analysis 144 | 145 | - *What is the cost to run the solution per day?* 146 | - *What does it cost to roll it out? * 147 | 148 | ### d. Security considerations 149 | 150 | - *What are the potential threats?* 151 | - *How will they be mitigated?* 152 | - *How will the solution affect the security of other components, services, and systems?* 153 | 154 | ### e. Privacy considerations 155 | 156 | - *Does the solution follow local laws and legal policies on data privacy?* 157 | - *How does the solution protect users’ data privacy?* 158 | - *What are some of the tradeoffs between personalization and privacy in the solution?* 159 | 160 | ### f. Regional considerations 161 | 162 | - *What is the impact of internationalization and localization on the solution?* 163 | - *What are the latency issues?* 164 | - *What are the legal concerns?* 165 | - *What is the state of service availability?* 166 | - *How will data transfer across regions be achieved and what are the concerns here?* 167 | 168 | ### g. Accessibility considerations 169 | 170 | - *How accessible is the solution?* 171 | - *What tools will you use to evaluate its accessibility?* 172 | 173 | ### h. Operational considerations 174 | 175 | - *Does this solution cause adverse aftereffects?* 176 | - *How will data be recovered in case of failure?* 177 | - *How will the solution recover in case of a failure?* 178 | - *How will operational costs be kept low while delivering increased value to the users?* 179 | 180 | ### i. Risks 181 | 182 | - *What risks are being undertaken with this solution?* 183 | - *Are there risks that once taken can’t be walked back?* 184 | - *What is the cost-benefit analysis of taking these risks?* 185 | 186 | ### j. Support considerations 187 | 188 | - *How will the support team get across information to users about common issues they may face while interacting with the changes?* 189 | - *How will we ensure that the users are satisfied with the solution and can interact with it with minimal support?* 190 | - *Who is responsible for the maintenance of the solution?* 191 | - *How will knowledge transfer be accomplished if the project owner is unavailable?* 192 | 193 | ## 5. Success Evaluation 194 | 195 | ### a. Impact 196 | 197 | - *Security impact* 198 | - *Performance impact* 199 | - *Cost impact* 200 | - *Impact on other components and services* 201 | 202 | ### b. Metrics 203 | 204 | - *List of metrics to capture* 205 | - *Tools to capture and measure metrics* 206 | 207 | ## 6. Work 208 | 209 | ### a. Work estimates and timelines 210 | 211 | - *List of specific, measurable, and time-bound tasks* 212 | - *Resources needed to finish each task* 213 | - *Time estimates for how long each task needs to be completed* 214 | 215 | ### b. Prioritization 216 | 217 | - *Categorization of tasks by urgency and impact* 218 | 219 | ### c. Milestones 220 | 221 | - *Dated checkpoints when significant chunks of work will have been completed* 222 | - *Metrics to indicate the passing of the milestone* 223 | 224 | ### d. Future work 225 | 226 | - *List of tasks that will be completed in the future* 227 | 228 | ## 7. Deliberation 229 | 230 | ### a. Discussion 231 | 232 | - *Elements of the solution that members of the team do not agree on and need to be debated further to reach a consensus.* 233 | 234 | ### b. Open Questions 235 | 236 | - *Questions about things you do not know the answers to or are unsure that you pose to the team and stakeholders for their input. These may include aspects of the problem you don’t know how to resolve - yet.* 237 | 238 | ## 8. End Matter 239 | 240 | ### a. Related Work 241 | 242 | - *Any work external to the proposed solution that is similar to it in some way and is worked on by different teams. It’s important to know this to enable knowledge sharing between such teams when faced with related problems.* 243 | 244 | ### b. References 245 | 246 | - *Links to documents and resources that you used when coming up with your design and wish to credit.* 247 | 248 | ### c. Acknowledgments 249 | 250 | - *Credit people who have contributed to the design that you wish to recognize.* 251 | -------------------------------------------------------------------------------- /tdd-workshop/presentation.md: -------------------------------------------------------------------------------- 1 | --- 2 | marp: true 3 | --- 4 | 5 | 6 | # How to write a Technical Design Document (TDD) 7 | 8 | ## Christy La Guardia, Senior Software Engineer, ClassPass 9 | 10 | 20 | 21 | --- 22 | # My coding journey 23 | 24 | ```js 25 | { 26 | 2008: "Learned to code as a mechanical engineering tech.", 27 | 2014: "Moved into a analysis and DBA role.", 28 | 2015: "Major life changes.", 29 | 2016: "Started Code Fellows bootcamp while working full-time, nights & weekends.", 30 | 2017: [ 31 | "Graduated from ACL advanced program.", 32 | "Humble brag: first student to get a real client for final project", 33 | "TA‘d after graduation", 34 | "First to work in AppLab." 35 | ], 36 | 2018: "Recruited by ClassPass, frontend focused.", 37 | 2021: "Started doing full-stack projects.", 38 | 2021: "Made it to Senior! Building out a new team and volunteering." 39 | } 40 | ``` 41 | 42 | --- 43 | 44 | # We'll cover 45 | 46 | 1. What is it? 47 | 2. Why is it needed? 48 | 3. How do you know if you need one? 49 | 4. How to write one? 50 | 5. Practice! 51 | 52 | --- 53 | 54 | # What is a Technical Design Document (TDD)? 55 | 56 | ## It's a document you will write before building something. It explains and validates your technical decisions and design. 57 | 58 | Typically, your engineering team will have a shared understanding of what it is and when to use it, and probably a template. (If not, you can bring it up!) 59 | 60 | a.k.a: Software Design Document, Engineering Design Document, Technical Specification 61 | 62 | --- 63 | 64 | # What is a Technical Design Document (TDD)? 65 | 66 | --- 67 | 68 | ## Examples 69 | 70 | - Creating a new large feature 71 | - Building a new web API 72 | - Implementing widespread design changes 73 | - Major library vision upgrade 74 | - Planning a large refactor 75 | - Burning down tech debt 76 | 77 | --- 78 | 79 | # These **challenging** questions will come up: 80 | 81 | - How are you going to build _____? 82 | - How long will it take to build _____? 83 | - Did you think of _____? 84 | - Why did you decide to use _____? 85 | - Is _____ in scope? 86 | - How much work is it to do _____? 87 | 88 | 94 | 95 | --- 96 | 97 | # How a TDD (or TDD-like) process will help you as a new engineer 98 | 99 | - Gives you a **structured** approach to taking on a big project and working through hard problems 100 | - Helps you have **confidence** in your design 101 | - Encourages **learning** from other engineers 102 | - Creates an **authoritative** source of truth for what you're building 103 | 104 | 108 | 109 | --- 110 | 111 | # How I felt about TDDs 112 | 113 | - I don’t know what this is. 114 | - I’m not qualified, this is a job for a senior engineer. 115 | - I don’t build anything that complex. 116 | - I don’t even know where to start. 117 | 118 | ![bg right:40% 80%](https://media.giphy.com/media/cLJdDcAWTkW6k/giphy.gif) 119 | 120 | 123 | 124 | --- 125 | 126 | # How I now feel about TDDs 127 | 128 | - I understand what a TDD is, and how to use it effectively. 129 | - This process can be followed by engineers at all levels, it’s a skill to be developed. 130 | - Even with simple tasks, a structured design process can speed up the implementation process and avoid reworks. 131 | - I know how to get started! 132 | 133 | ![bg right:40% 80%](https://media.giphy.com/media/YFis3URdQJ6qA/giphy.gif) 134 | 135 | 138 | 139 | --- 140 | 141 | # Advantages of writing a TDD 142 | 143 | - Forces you to examine a problem (*before* coding) 144 | - Identifies missing requirements 145 | - Helps the team collaborate 146 | - Ship faster 147 | - Prevents scope creep 148 | - Helps resolve problems that pop up later 149 | - Serves as documentation 150 | - Saves time & money! 151 | 152 | --- 153 | 154 | # Disadvantages of writing a TDD 155 | 156 | - Upfront cost (time) 157 | 158 | --- 159 | 160 | # Getting Started 161 | 162 | --- 163 | 164 | # When do you need a TDD? 165 | 166 | - No industry standard or hard-and-fast rules 167 | - Your team should set the prerequisite criteria (doesn't including finalized product or design requirements) 168 | - You should carefully weigh the cost vs. benefit 169 | 170 | --- 171 | 172 | # From the ClassPass docs: 173 | 174 | *Any project that we estimate will take more than 2 weeks for one engineer to complete requires a TDD and getting feedback from the engineering team.* 175 | 176 | --- 177 | 178 | 179 | ![bg contain](https://i.imgur.com/rCr9A.png) 180 | 181 | --- 182 | 183 | 184 | ![bg contain](https://artprojectsforkids.org/wp-content/uploads/2021/10/How-to-Draw-an-Owl-Face-diagram.jpg) 185 | 186 | 187 | --- 188 | 189 | 190 | ![bg contain](https://www.projecttimes.com/wp-content/themes/yootheme/cache/ad0145173c00f7fe99af7442fbe6a818-a6198ff7.jpeg) 191 | 192 | 193 | --- 194 | 195 | # Factors to consider when deciding to write a TDD 196 | 197 | 1. Size 198 | 1. Complexity 199 | 1. Uncertainty 200 | 1. Dependencies 201 | 202 | --- 203 | 204 | # 1. Size 205 | 206 | What is the amount work? 207 | How long will it take? 208 | How many engineers? 209 | 1 day? 210 | 1 week? 211 | 1 month? 212 | Have no idea? 213 | 214 | --- 215 | 216 | # 2. Complexity 217 | 218 | Lots of logic? 219 | Business rules or logic? 220 | Intricate UI? 221 | A new server or service? 222 | Data changes or big database migrations? 223 | 224 | --- 225 | 226 | # 3. Uncertainty 227 | 228 | Introducing a new technology or library? 229 | Language or framework the team is unfamiliar with? 230 | How will these changes rollout? 231 | Known issues or tech debt? 232 | 233 | --- 234 | 235 | # 4. Dependencies 236 | 237 | ## Internal 238 | 239 | Will this be used by another team? 240 | Will this impact another team’s system? 241 | 242 | ## External 243 | 244 | Adding a new vendor? 245 | What are the costs? 246 | What are the maintenance costs? 247 | 248 | --- 249 | 250 | # Still not sure? 251 | 252 | Consider doing some research, exploratory work or a spike with the goal to gather information in order to make a decision on the path forward. 253 | 254 | (See the [discovery template](templates/discovery.md).) 255 | 256 | --- 257 | 258 | # Example 1 259 | 260 | You have been asked to add a “Get in touch” button to an existing web page. 261 | When clicked, this button will open up the the existing “Contact Us” page in a new window. 262 | 263 | *Size? Complexity? Uncertainty? Dependencies? . . . Should you write a TDD?* 264 | 265 | 272 | 273 | --- 274 | 275 | # Example 2 276 | 277 | In addition, you’ve been asked to add a form to the “Contact Us” page, so that the user can submit their message without using email. 278 | 279 | *Size? Complexity? Uncertainty? Dependencies? . . . Should you write a TDD?* 280 | 281 | 288 | 289 | --- 290 | 291 | # Example 3 292 | 293 | To allow the customer service team to reply to the “Contact Us” messages, they should be distributed evenly to customer service representatives. Ensure that messages are replied to in the order received and priority. Customer service team managers should be able to view all incoming and outgoing messages, and the messages assigned to each representatives. Also, we’d like to see a dashboard with a summary of total messages received and sent, so we can monitor work load and track growth. 294 | 295 | *Size? Complexity? Uncertainty? Dependencies? . . . Should you write a TDD?* 296 | 297 | 304 | 305 | --- 306 | 307 | # Sections of the TDD 308 | 309 | 1. Explain 310 | 2. Plan 311 | 3. Decide 312 | 313 | 314 | 315 | --- 316 | 317 | # 1. Explain 318 | 319 | ## Introduction, Context, Problem/Solution, Goals/Non-Goals 320 | 321 | What problem are you trying to solve? 322 | Why does it need to be solved? What is the impact? 323 | What are the goals of this project? 324 | What contextual or background information should the reader know? 325 | 326 | --- 327 | 328 | # 2. Plan 329 | 330 | ## Technical Approach, Considerations, Phases/Steps 331 | 332 | How are you going to solve the problem? 333 | What are the technical implementation details? 334 | What factors are relevant or need special consideration? 335 | 336 | --- 337 | 338 | # 3. Decide 339 | 340 | ## Options, Alternatives, Release 341 | 342 | What is the time and effort to implement? 343 | Are there alternatives? What are the costs? 344 | Any future work? Maintenance? 345 | 346 | --- 347 | 348 | # TDD Tips 349 | 350 | --- 351 | 352 | # Estimating *Level of Effort* (LOE) using T-Shirt sizes 353 | 354 | Using T-Shirt sizes to give estimates of LOE is really helpful when you can’t give exact estimates. 355 | 356 | | Size | Example Time Estimate | 357 | | ---- | --------------------- | 358 | | XS | 1 or 2 days | 359 | | S | 1 week | 360 | | M | 2 weeks | 361 | | L | 4 weeks | 362 | | XL | Anything more | 363 | 364 | --- 365 | 366 | # Consider your audience 367 | 368 | - Fellow engineers 369 | - Engineering managers 370 | - Product manager? 371 | - Designers? 372 | - Project mangers? 373 | - Stakeholders? 374 | 375 | --- 376 | 377 | # Proofreading 378 | 379 | - Look for unfounded assumptions ("This always works." "This will be easy.") 380 | - Edit subjective words ("I feel", "I think", "Good/bad") 381 | - Make sure it sounds professional (No "hey guys") 382 | - Use correct spelling and grammar 383 | 384 | --- 385 | 386 | # Reviewing and commenting 387 | 388 | 1. Decide who to share it with 389 | 2. Ask feedback & reviews 390 | 3. May want to lead a meeting 391 | 4. Reply to comments, answer questions 392 | 5. Revise your TDD 393 | 6. Consider keeping it updated or additional docs 394 | 7. Make a decision and start coding! 395 | 396 | --- 397 | 398 | # Examples 399 | 400 | - [Simple](/templates/simple-example.md) 401 | - [Practical](/templates/practical-example.md) -------------------------------------------------------------------------------- /tdd-workshop/index.html: -------------------------------------------------------------------------------- 1 |
13 |

How to write a Technical Design Document (TDD)

14 |

Christy La Guardia, Senior Software Engineer, ClassPass

15 |
16 |
17 |

My coding journey

18 | 
{
 19 |   2008: "Learned to code as a mechanical engineering tech.",
 20 |   2014: "Moved into a analysis and DBA role.",
 21 |   2015: "Major life changes.",
 22 |   2016: "Started Code Fellows bootcamp while working full-time, nights & weekends.",
 23 |   2017: [
 24 |     "Graduated from ACL advanced program.",
 25 |     "Humble brag: first student to get a real client for final project",
 26 |     "TA‘d after graduation",
 27 |     "First to work in AppLab."
 28 |   ],
 29 |   2018: "Recruited by ClassPass, frontend focused.",
 30 |   2021: "Started doing full-stack projects.",
 31 |   2021: "Made it to Senior! Building out a new team and volunteering."
 32 | }
 33 |
34 |
35 |
36 |

We'll cover

37 |
    38 |
  1. What is it?
    2. 39 |
  2. Why is it needed?
    3. 40 |
  3. How do you know if you need one?
    4. 41 |
  4. How to write one?
    5. 42 |
  5. Practice!
    6. 43 |
44 |
45 |
46 |

What is a Technical Design Document (TDD)?

47 |

It's a document you will write before building something. It explains and validates your technical decisions and design.

48 |

Typically, your engineering team will have a shared understanding of what it is and when to use it, and probably a template. (If not, you can bring it up!)

49 |

a.k.a: Software Design Document, Engineering Design Document, Technical Specification

50 |
51 |
52 |

What is a Technical Design Document (TDD)?

53 |
54 |
55 |

Examples

56 |
    57 |
  • Creating a new large feature
    • 58 |
  • Building a new web API
    • 59 |
  • Implementing widespread design changes
    • 60 |
  • Major library vision upgrade
    • 61 |
  • Planning a large refactor
    • 62 |
  • Burning down tech debt
    • 63 |
64 |
65 |
66 |

These challenging questions will come up:

67 |
    68 |
  • How are you going to build _____?
    • 69 |
  • How long will it take to build _____?
    • 70 |
  • Did you think of _____?
    • 71 |
  • Why did you decide to use _____?
    • 72 |
  • Is _____ in scope?
    • 73 |
  • How much work is it to do _____?
    • 74 |
75 |
76 |
77 |

How a TDD (or TDD-like) process will help you as a new engineer

78 |
    79 |
  • Gives you a structured approach to taking on a big project and working through hard problems
    • 80 |
  • Helps you have confidence in your design
    • 81 |
  • Encourages learning from other engineers
    • 82 |
  • Creates an authoritative source of truth for what you're building
    • 83 |
84 |
85 |
86 |

How I felt about TDDs

87 |
    88 |
  • I don’t know what this is.
    • 89 |
  • I’m not qualified, this is a job for a senior engineer.
    • 90 |
  • I don’t build anything that complex.
    • 91 |
  • I don’t even know where to start.
    • 92 |
93 |
94 |
95 |

How I now feel about TDDs

96 |
    97 |
  • I understand what a TDD is, and how to use it effectively.
    • 98 |
  • This process can be followed by engineers at all levels, it’s a skill to be developed.
    • 99 |
  • Even with simple tasks, a structured design process can speed up the implementation process and avoid reworks.
    • 100 |
  • I know how to get started!
    • 101 |
102 |
103 |
104 |

Advantages of writing a TDD

105 |
    106 |
  • Forces you to examine a problem (before coding)
    • 107 |
  • Identifies missing requirements
    • 108 |
  • Helps the team collaborate
    • 109 |
  • Ship faster
    • 110 |
  • Prevents scope creep
    • 111 |
  • Helps resolve problems that pop up later
    • 112 |
  • Serves as documentation
    • 113 |
  • Saves time & money!
    • 114 |
115 |
116 |
117 |

Disadvantages of writing a TDD

118 |
    119 |
  • Upfront cost (time)
    • 120 |
121 |
122 |
123 |

Getting Started

124 |
125 |
126 |

When do you need a TDD?

127 |
    128 |
  • No industry standard or hard-and-fast rules
    • 129 |
  • Your team should set the prerequisite criteria (doesn't including finalized product or design requirements)
    • 130 |
  • You should carefully weigh the cost vs. benefit
    • 131 |
132 |
133 |
134 |

From the ClassPass docs:

135 |

Any project that we estimate will take more than 2 weeks for one engineer to complete requires a TDD and getting feedback from the engineering team.

136 |
137 |
138 |
139 |
140 |
141 |

Factors to consider when deciding to write a TDD

142 |
    143 |
  1. Size
    2. 144 |
  2. Complexity
    3. 145 |
  3. Uncertainty
    4. 146 |
  4. Dependencies
    5. 147 |
148 |
149 |
150 |

1. Size

151 |

What is the amount work?
152 | How long will it take?
153 | How many engineers?
154 | 1 day?
155 | 1 week?
156 | 1 month?
157 | Have no idea?

158 |
159 |
160 |

2. Complexity

161 |

Lots of logic?
162 | Business rules or logic?
163 | Intricate UI?
164 | A new server or service?
165 | Data changes or big database migrations?

166 |
167 |
168 |

3. Uncertainty

169 |

Introducing a new technology or library?
170 | Language or framework the team is unfamiliar with?
171 | How will these changes rollout?
172 | Known issues or tech debt?

173 |
174 |
175 |

4. Dependencies

176 |

Internal

177 |

Will this be used by another team?
178 | Will this impact another team’s system?

179 |

External

180 |

Adding a new vendor?
181 | What are the costs?
182 | What are the maintenance costs?

183 |
184 |
185 |

Still not sure?

186 |

Consider doing some research, exploratory work or a spike with the goal to gather information in order to make a decision on the path forward.

187 |

(See the discovery template.)

188 |
189 |
190 |

Example 1

191 |

You have been asked to add a “Get in touch” button to an existing web page.
192 | When clicked, this button will open up the the existing “Contact Us” page in a new window.

193 |

Size? Complexity? Uncertainty? Dependencies? . . . Should you write a TDD?

194 |
195 |
196 |

Example 2

197 |

In addition, you’ve been asked to add a form to the “Contact Us” page, so that the user can submit their message without using email.

198 |

Size? Complexity? Uncertainty? Dependencies? . . . Should you write a TDD?

199 |
200 |
201 |

Example 3

202 |

To allow the customer service team to reply to the “Contact Us” messages, they should be distributed evenly to customer service representatives. Ensure that messages are replied to in the order received and priority. Customer service team managers should be able to view all incoming and outgoing messages, and the messages assigned to each representatives. Also, we’d like to see a dashboard with a summary of total messages received and sent, so we can monitor work load and track growth.

203 |

Size? Complexity? Uncertainty? Dependencies? . . . Should you write a TDD?

204 |
205 |
206 |

Sections of the TDD

207 |
    208 |
  1. Explain
    2. 209 |
  2. Plan
    3. 210 |
  3. Decide
    4. 211 |
212 |
213 |
214 |

1. Explain

215 |

Introduction, Context, Problem/Solution, Goals/Non-Goals

216 |

What problem are you trying to solve?
217 | Why does it need to be solved? What is the impact?
218 | What are the goals of this project?
219 | What contextual or background information should the reader know?

220 |
221 |
222 |

2. Plan

223 |

Technical Approach, Considerations, Phases/Steps

224 |

How are you going to solve the problem?
225 | What are the technical implementation details?
226 | What factors are relevant or need special consideration?

227 |
228 |
229 |

3. Decide

230 |

Options, Alternatives, Release

231 |

What is the time and effort to implement?
232 | Are there alternatives? What are the costs?
233 | Any future work? Maintenance?

234 |
235 |
236 |

TDD Tips

237 |
238 |
239 |

Estimating Level of Effort (LOE) using T-Shirt sizes

240 |

Using T-Shirt sizes to give estimates of LOE is really helpful when you can’t give exact estimates.

241 | 242 | 243 | 244 | 245 | 246 | 247 | 248 | 249 | 250 | 251 | 252 | 253 | 254 | 255 | 256 | 257 | 258 | 259 | 260 | 261 | 262 | 263 | 264 | 265 | 266 | 267 | 268 | 269 | 270 |
SizeExample Time Estimate
XS1 or 2 days
S1 week
M2 weeks
L4 weeks
XLAnything more
271 |
272 |
273 |

Consider your audience

274 |
    275 |
  • Fellow engineers
    • 276 |
  • Engineering managers
    • 277 |
  • Product manager?
    • 278 |
  • Designers?
    • 279 |
  • Project mangers?
    • 280 |
  • Stakeholders?
    • 281 |
282 |
283 |
284 |

Proofreading

285 |
    286 |
  • Look for unfounded assumptions ("This always works." "This will be easy.")
    • 287 |
  • Edit subjective words ("I feel", "I think", "Good/bad")
    • 288 |
  • Make sure it sounds professional (No "hey guys")
    • 289 |
  • Use correct spelling and grammar
    • 290 |
291 |
292 |
293 |

Reviewing and commenting

294 |
    295 |
  1. Decide who to share it with
    2. 296 |
  2. Ask feedback & reviews
    3. 297 |
  3. May want to lead a meeting
    4. 298 |
  4. Reply to comments, answer questions
    5. 299 |
  5. Revise your TDD
    6. 300 |
  6. Consider keeping it updated or additional docs
    7. 301 |
  7. Make a decision and start coding!
    8. 302 |
303 |
304 |
305 |

Examples

306 | 310 |
311 |

Pre-start questions: 313 | - Where are you in the program? 314 | - What did you do before code school? 315 | - Have you ever heard of a TDD? 316 | For the workshop: 317 | - Conformable with git work flow? 318 | - PR reviews? 319 | - Markdown?

Notes: 320 | - Intimidating questions, see them as an opportunity 321 | - I wasn't prepared for this 322 | - Made the mistake of way over/under estimating

Notes: I had a hard time with developer vs. engineer, and believing I was past entry-level. 323 | The TDD process was CRITICAL to advancing to Mid and Senior levels.

Notes: Felt like something I had to get over with so I could get to coding.

Notes: It's a tool I keep in my back pocket.

How to draw an owl meme

Kids guide to drawing an owl

Source: [Easy How to Draw an Owl Face Tutorial and Owl Face Coloring Page](https://artprojectsforkids.org/how-to-draw-an-owl-face/)

Difficulty and complexity diagram

Source: [A Simplified Approach To Determine IT Project Complexity](https://www.projecttimes.com/articles/a-simplified-approach-to-determine-it-project-complexity/)

Notes: 324 | - Size: How much? How long? How many people? 325 | - Complexity: Logic? Rules? UI? New thing? Data? 326 | - Uncertainty: New tech? Familiarity? Known issues? 327 | - Dependencies: Used internally? New dependencies?

Notes: 328 | - Size: How much? How long? How many people? 329 | - Complexity: Logic? Rules? UI? New thing? Data? 330 | - Uncertainty: New tech? Familiarity? Known issues? 331 | - Dependencies: Used internally? New dependencies?

Notes: 332 | - Size: How much? How long? How many people? 333 | - Complexity: Logic? Rules? UI? New thing? Data? 334 | - Uncertainty: New tech? Familiarity? Known issues? 335 | - Dependencies: Used internally? New dependencies?

Notes: This is a high-level overview, each template has a different structure.

--------------------------------------------------------------------------------