<?xml version="1.0" encoding="UTF-8"?><rss xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:atom="http://www.w3.org/2005/Atom" version="2.0" xmlns:cc="http://cyber.law.harvard.edu/rss/creativeCommonsRssModule.html">
    <channel>
        <title><![CDATA[Stories by Mike Rogers on Medium]]></title>
        <description><![CDATA[Stories by Mike Rogers on Medium]]></description>
        <link>https://medium.com/@mikerogers_?source=rss-c1d181b746de------2</link>
        <image>
            <url>https://cdn-images-1.medium.com/fit/c/150/150/0*FAfVuU-pQPEDQioX.jpg</url>
            <title>Stories by Mike Rogers on Medium</title>
            <link>https://medium.com/@mikerogers_?source=rss-c1d181b746de------2</link>
        </image>
        <generator>Medium</generator>
        <lastBuildDate>Fri, 20 Nov 2026 07:07:34 GMT</lastBuildDate>
        <atom:link href="https://medium.com/@mikerogers_/feed" rel="self" type="application/rss+xml"/>
        <webMaster><![CDATA[yourfriends@medium.com]]></webMaster>
        <atom:link href="http://medium.superfeedr.com/" rel="hub"/>
        <item>
            <title><![CDATA[Washing Machines and API Design]]></title>
            <link>https://medium.com/@mikerogers_/washing-machines-and-api-design-87bc18a319de?source=rss-c1d181b746de------2</link>
            <guid isPermaLink="false">https://medium.com/p/87bc18a319de</guid>
            <dc:creator><![CDATA[Mike Rogers]]></dc:creator>
            <pubDate>Mon, 14 Nov 2016 17:11:01 GMT</pubDate>
            <atom:updated>2016-11-14T17:11:01.313Z</atom:updated>
            <content:encoded><![CDATA[<p>The day my daughter was born was the same day that my washing machine broke. For those of you who’ve never had to deal with a newborn, what that means is that I was tasked with fixing a washing machine while sleep deprived to the point of IQ loss.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/360/1*qP-DWStuYuPVTGyLOI4bxw.png" /><figcaption>Two things that do not result in clean clothes</figcaption></figure><p>Having never fixed a washing machine before, I turned to Google. After a few frantic searches I turned up an article that suggested I watch a video. The article said that the video wasn’t going to fix my problem; “just watch it long enough to disassemble the machine and gain access to the diagnostic booklet.”</p><p>… Wait, what?</p><h4>Washing Machines have Diagnostic Booklets</h4><p>This isn’t one of those things we covered in “Adulting 101” back in high school [<em>ed: that’s not a real class</em>], but apparently many models of washing machine have a plastic sleeve on the inside of their case that contains a booklet to help a technician diagnose problems the machine is having.</p><p>Sure enough I found the booklet right where the video indicated. It laid out the sequence of knob rotations necessary to put the machine into a <em>diagnostic mode</em>, which allowed me to:</p><ul><li>Check the last four Diagnostic Trouble Codes</li><li>Run an automated test suite</li><li>Manually run tests on individual components</li></ul><p>So I looked up the most recent trouble codes, which took the form of a blinkenlight sequence. The booklet told me that the particular sequence indicated a problem filling the washer basin within a specified timeout. <strong>Not only that</strong>, the booklet also indicated what troubleshooting steps to take so that I could diagnose the underlying problem and correct it.</p><p>Using the booklet and the manual tests I was able to isolate the problem as a bad cold water solenoid. I ordered the replacement part off Amazon, installed it, and my washer worked wonderfully (which I verified again with the manual tests available through the diagnostic mode).</p><h4>What a Well Designed Experience</h4><p>Have you ever consumed an API like my washing machine’s interface? Something with specialized documentation? Meaningful error messages, a diagnostic mode, a troubleshooting guide?</p><p>Have you ever <em>designed</em> such an API?</p><p>I read an article recently on <a href="https://medium.freecodecamp.com/https-medium-com-anupcowkur-how-to-design-apis-that-dont-suck-922d864365c9">designing APIs that don’t suck</a>. All the ideas were spot on; the ones I want to focus on are “Document all the things” and “Make it testable”, as well as taking the time to create your own tools to help consumers.</p><p>Imagine how difficult it would’ve been to fix my washing machine if the manufacturer hadn’t made it testable or invested in documentation. Given how sleep deprived I was it’s easy to speculate that, without the booklet, I could’ve shocked myself severely, burned my house down, or ruined my credit rating somehow.</p><p>Simply knowing that the tools and docs were available left me feeling relaxed and confident. I knew someone had designed this interaction and, given the thoroughness of the documentation, I felt they had been comprehensive. I wasn’t out on a limb, exploring the frontier of integration; all that work had been done already and was collected into an easy-to-consume package.</p><p>How can I get that for my API?</p><h4>Designing your API’s Documentation</h4><p>Look. I love you and I love TDD but you’re wrong if you think your TDD tests are documentation. TDD tests are small units of execution meant to help you refactor your code into a more manageable state while maintaining correct behavior. People who consume your API need more than the breadcrumbs on your path to implementation.</p><p>The article linked above suggests the following for documentation, above and beyond any tests you write:</p><blockquote>1. A high level overview of the whole module and how it works</blockquote><blockquote>2. Javadocs, Heredocs, Rdocs or whatever of its public methods and protocols</blockquote><blockquote>3. Sample code showing how to use it</blockquote><p>That’s a great list. I would add “Common problems and how to solve them”, although some people may assume that’s part of #3.</p><p>A common complaint from developers is that documentation is stale as soon as it’s written. How do you keep these documents up-to-date?</p><p>Simple. Keep them in source control alongside your code and fold modifications to them into your workflow. If you have a work item in your tracker for modifying an API method, ensure that the work item also reminds you to modify the document. Make sure the document is included in your code review process. When you generate your deployable artifact make sure the document is also included in the artifact (as a PDF or static HTML pages or something).</p><p>I worked on a project a while back that took this approach, keeping the live documentation in Markdown right next to the code for the system it described. Developers modified the documentation frequently, and we had automated build tasks to generate documentation artifacts, which were versioned similarly to our software.</p><h4>Designing your API’s Tools</h4><p>I admit I am very weak in this area. But I have encountered some really cool tools that reflect the kind of values I’m describing.</p><p>Let’s look at the AWS IoT Dashboard:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*pZiSCTQeRINOW2TkByjAtQ.png" /><figcaption>AWS IoT Dashboard</figcaption></figure><p>That link up there on the right? MQTT Client? That guy can be used to ensure that the IoT Topics and Rules are configured correctly. It’s all right here in this <a href="http://docs.aws.amazon.com/iot/latest/developerguide/config-and-test-rules.html">comprehensive documentation</a>. Amazon took the time to write great docs and tooling and using their stuff is super nice.</p><p>Once you get your tooling in place you should probably set up some <a href="https://jenkins.io/index.html">builds</a> that use your tools to <a href="https://en.wikipedia.org/wiki/Eating_your_own_dog_food">test your own APIs</a>. That’s in addition to builds for your tools and builds for your APIs.</p><h4>My washing machine is fixed</h4><p>I, like you, have coded to an undocumented API or two. For the longest time I believed that API documentation only took the form of JavaDocs with sparse comments. It took fixing my washing machine to see that I can do much, much better. The next time I have to design an API you can bet I’ll be paying more attention to the experience of the consumers.</p><p>It would be great to learn these lessons without, you know, having a major appliance break down on me.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=87bc18a319de" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[My manager gave me an AWS IoT Button]]></title>
            <link>https://medium.com/@mikerogers_/my-manager-gave-me-an-aws-iot-button-8e3c77ca1732?source=rss-c1d181b746de------2</link>
            <guid isPermaLink="false">https://medium.com/p/8e3c77ca1732</guid>
            <category><![CDATA[aws]]></category>
            <category><![CDATA[iot]]></category>
            <category><![CDATA[aws-iot]]></category>
            <dc:creator><![CDATA[Mike Rogers]]></dc:creator>
            <pubDate>Sat, 24 Sep 2016 19:43:05 GMT</pubDate>
            <atom:updated>2016-09-24T19:43:05.607Z</atom:updated>
            <content:encoded><![CDATA[<h4>With the touch of a button you can notify the world that you touched a button.</h4><p>I was sitting at my desk the other day, busily shifting paradigms and engaging synergies, when my manager plopped a small brown paper box on my desk.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/200/1*p0zqvnZtthsaKKIuLk8ADQ.jpeg" /><figcaption>*plop*</figcaption></figure><p>“What’s this?” I asked, setting aside my efforts to break down silos through gamified product-thinking.</p><p>“It’s an AWS IoT Button. From Amazon. Do something cool and write about it,” he replied.</p><h4>AWS IoT Button?</h4><p>I knew of <a href="https://aws.amazon.com/">AWS</a> — who doesn’t? But I didn’t know they had an <a href="https://aws.amazon.com/iot/">Internet of Things</a> offering. So the first step was to visit the page and…</p><p>Wow, that’s complicated.</p><p>So I turned my attention to the <a href="https://aws.amazon.com/iot/button">button</a>. And the documentation was pretty understandable. Within an hour I had hooked the button into the team’s Slack channel, thanks largely to a pre-existing <a href="https://aws.amazon.com/blogs/aws/new-slack-integration-blueprints-for-aws-lambda/">AWS Lambda blueprint</a> for Slack integration.</p><p>This is all kinds of fantastic for me. With the touch of a button I can execute more code than all the Apollo missions combined <em>and</em> annoy my team by spamming the Slack channel?</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/320/1*0Y2ejN7kaBt_6IS6nnXQpg.jpeg" /></figure><p>But what exactly does the button <em>do</em>? Like, under the hood?</p><h4>Good question, Mike</h4><p>Thanks, header!</p><p>Under the hood we’re taking advantage of a slew of AWS IoT features:</p><ol><li>The Thing — in this case, the button itself. IoT maintains a Registry of all your Things, which can be given a Thing Type and a couple of searchable attributes. You link Things with Certificates.</li><li>Certificates — these are generated to enable mutual authentication between the Thing and AWS. Certificates also link Things to Policies.</li><li>Policies — these are JSON documents that grant your Things specific access to specific resources on behalf of specific users. I think. The Button uses a Policy to tie a Thing to a Topic.</li><li>Topics — imagine a fancy publish/subscriber queue. Things generate data, and when they do the data will usually end up being pushed to one of these Topics to be consumed by a Rule.</li><li>Rules — here’s where things get interesting. These Rules are simple <a href="https://en.wikipedia.org/wiki/Business_rule">business rules</a>, as in a <a href="http://www.drools.org/">rules engine</a>. On a truthful evaluation of a business rule (given the input from your Thing) the data can be dispersed to any one of AWS’s many Services via an Action.</li><li>Actions — one of AWS’s many services. Such as Lambda, which is what I used to trigger the Slack integration.</li></ol><p>Okay, that’s a lot of background, so let’s go through the Button example.</p><p>I press the Button, which initiates Internal Button Logic. This logic connects (via Certificate) to the AWS IoT endpoint assigned to the Button (which is a Thing in the Registry). When the connection is established and authenticated the Button uploads its state data (what kind of click, how much battery power is left, and its identifier) to the IoT endpoint.</p><p>So far so good.</p><p>When the IoT endpoint receives the data it publishes it to the associated Topic (which is known via the Thing’s Certificate’s Policy). A Rule is watching this Topic and, when it notices the incoming data, evaluates it against the Rule’s conditional (for the button the conditional is “is there data?” since data is only uploaded on a click event). Assuming truthful evaluation, the data is then shipped off to the associated Action. Which in this case is an AWS Lambda. A Lambda that annoys my team.</p><h4>Next steps?</h4><p>It turns out you can buy <a href="https://www.amazon.com/s/ref=nb_sb_noss?url=search-alias%3Daps&amp;field-keywords=aws+iot+kit">many different AWS IoT kits</a> on, of all places, Amazon. I imagine the kits take advantage of some of the IoT code provided by AWS, such as the <a href="https://aws.amazon.com/iot/sdk/">C, Arduino, and JavaScript SDKs</a>.</p><p>As for me, I’ll have to wait for my manager to interrupt me again with a new toy. I don’t have time to invest in this IoT stuff while there are all these glass ceilings to leverage via B2B mindshare.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=8e3c77ca1732" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Estimation without estimating: how long will it take?]]></title>
            <link>https://medium.com/@mikerogers_/estimation-without-estimating-how-long-will-it-take-830a0fc9769f?source=rss-c1d181b746de------2</link>
            <guid isPermaLink="false">https://medium.com/p/830a0fc9769f</guid>
            <category><![CDATA[statistics]]></category>
            <category><![CDATA[estimations]]></category>
            <category><![CDATA[agile]]></category>
            <category><![CDATA[noestimates]]></category>
            <category><![CDATA[scrum]]></category>
            <dc:creator><![CDATA[Mike Rogers]]></dc:creator>
            <pubDate>Tue, 26 Jul 2016 17:42:52 GMT</pubDate>
            <atom:updated>2016-07-26T17:42:52.288Z</atom:updated>
            <content:encoded><![CDATA[<p>It’s a question that development teams dread:</p><blockquote>There are 100 stories left until our major release. When will they be finished?</blockquote><p>Let’s try to answer this without doing any guessing about how big stories are or how long they will take, which I’ve never been super comfortable doing. Instead we’ll look at historical data and generate a reasonable and quick forecast.</p><p>This method of estimation is quite interesting and easy to wrap your mind around. I almost titled this article “You can avoid estimating with this one weird trick”.</p><h4>Getting started</h4><p>My team is <a href="https://neilkillick.wordpress.com/2016/05/31/my-slicing-heuristic-concept-explained/">slicing stories</a> as reasonably small as we can get them while still remaining valuable. I bring this up because we’re going to be <a href="http://martinfowler.com/bliki/StoryCounting.html">counting stories</a> to give ourselves an idea of how much we can do per sprint, and if we’re not intentional about how stories are sliced then counting may give us a false sense of progress.</p><p>Let’s look at some data I happen to have lying around in my Work Tracking Software:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/257/1*EI6VD0j-HBTdhr0fYXgxQQ.png" /><figcaption>Actual historical data™</figcaption></figure><p>After 10 sprints our low count is 5 and our high count is 15. Awesome. Let’s do some predicting. Remember the original question: <em>how long will it take to finish 100 things?</em></p><p>Easy easy easy. Look at our historical data. The least we’ve gotten done in a sprint is 5 things, so <em>at most</em> it’ll probably be 20 sprints (100 ÷ 5 = 20). Similarly, the <em>most</em> we’ve gotten done in a sprint is 15 things, so the<em> least</em> it will be is 7 sprints (100 ÷ 15 = 7, rounded up).</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/129/1*YpKBzXJow8oUTtXsbQNAQg.png" /><figcaption>We’ll call these ‘theoretical min and max’ since they’re not at all practical</figcaption></figure><p>So already we have a very high confidence that the work will take between 7 and 20 sprints. That’s certainly helpful, but can we quantify that confidence? And maybe get a little more precise?</p><h4>Quantifying confidence and getting more precise</h4><p>Okay, this is going to sound a little weird, but here’s what we’re going to do:</p><p>We’re going to simulate one thousand potential outcomes. That is, we’re going to pretend to finish 100 stories using randomized historical data to see how long it <em>might</em> take, one thousand times.</p><p>Don’t panic. It’s not that hard to simulate a single potential outcome, which I’ll call a <strong>trial</strong>. And once we have <em>one</em> trial it won’t be difficult to scale up. Remember: we have Real Data to guide us. Check this out:</p><ol><li>Roll a 10-sided die (because we have 10 sprints of data)</li><li>Whatever number comes up (<em>x</em>) is the sprint we’re going to look at. Check the chart above and write down the count of things completed for sprint <em>x</em></li><li>Go to step 1 until the sum of the numbers written down is greater than our target count, which is 100</li><li>Observe how many numbers you’ve written down. That’s how many sprints it took for this particular trial</li></ol><p>I’ll roll a trial while sitting here:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/391/1*vC_t7hGbb4sf3NkprfgjZg.png" /><figcaption>Actual random values™</figcaption></figure><p>That’s all there is to it. Roll a die and select that sprint’s count until the total is above 100 and note how many times you rolled the die. This particular trial indicates that the work will be done in 13 sprints because there were 13 rolls of the die to get the count above 100.</p><p>Trial 1: 13 sprints.</p><p>Now do that 999 more times. You can automate it if you want to; I’ll make no disparaging comments. Aloud. Anyway, you’ll start to see something like this:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/480/1*eiK4X8Bl1nPfZ_oTS4Vbgw.png" /><figcaption>Small batch, artisanal data</figcaption></figure><p>Awesome. Now let’s talk about confidence intervals.</p><p>Take a look at that chart. We are 100% confident we can get the work done in 17 sprints because no trial took more than 17 iterations to complete. Conversely, if you run the numbers, we’re only 5% confident that we can finish in 11 sprints. That means, statistically, that 10 sprints and fewer are <em>right out</em>. So above, when we said “it could get done in as few as 7 sprints” we were <em>way, way wrong</em>. By a factor of at least 2, it looks like.</p><p>Here are some real confidence values:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/354/1*ZyP_LAxy02Z6EQNdXGil-w.png" /><figcaption>Look at all that confidence</figcaption></figure><p>It looks like 15 sprints is a pretty reasonable bet, but really this is a conversation you want to have with your stakeholders. How much risk are they willing to take on? For example, if they wanted to be aggressive they may want to target 13 sprints, although I would make sure they understood there’s only a 50% chance we’d make it, according to the data.</p><p>I love being able to say that: <em>according to the data</em>.</p><h4>Wrapping things up</h4><p>Where do you go from here? Why, continue collecting data, of course! Delivering an estimate is not a reason to stop communicating. As you complete each new sprint, add the ‘count of things done’ to your historical data pool and run more simulations to re-assess how closely you’re tracking to your original estimate. When things deviate, have a conversation with your stakeholders and let them know.</p><p>I really like this method of estimation because it avoids the unpleasant business of pretending I can tell the future. I don’t have to say “based on my experience this work will probably take us <em>very long.</em>” I can instead say “it will take <em>this long</em> with <em>this confidence level. </em>Here’s the math — I can walk you through it and the answer won’t change until we get more data, and then the answer will only be <em>more accurate</em>”.</p><p>And of course…</p><blockquote>Cognitive psychology tells us that the unaided human mind is vulnerable to many fallacies and illusions because of its reliance on its memory for vivid anecdotes rather than systematic statistics. — Steven Pinker</blockquote><p>… it’s harder to lie to yourself if you’re using data.</p><h4>Further reading</h4><p>This approach is called the <a href="https://en.wikipedia.org/wiki/Monte_Carlo_method">Monte Carlo method</a>. The guy I know of out there doing the most with this technique is Troy Magennis, who has some wonderful resources at <a href="http://focusedobjective.com/">Focused Objective’s website</a>, including a white paper on <a href="http://focusedobjective.com/wp-content/uploads/2014/09/The-Economic-Impact-of-Software-Development-Process-Choice-Cycle-time-Analysis-and-Monte-Carlo-Simulation-Results.pdf">the shape of cycle time data</a> — a must-read if you’re doing any kind of professional estimation.</p><p>Larry Maccherone has a great visualization of the content of this article at his project <a href="http://lumenize.com/">Lumenize</a>. It’s an effective way to demonstrate the power of running simulations based on historical data.</p><p>I’d also like to plug Johanna Rothman’s book <a href="http://www.jrothman.com/books/predicting-the-unpredictable-pragmatic-approaches-to-estimating-cost-or-schedule/">Predicting the Unpredictable</a>, which to my recollection didn’t have much in the way of Monte Carlo-based simulation, but was certainly very formative in my approach to estimation.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=830a0fc9769f" width="1" height="1" alt="">]]></content:encoded>
        </item>
    </channel>
</rss>