<?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 Christian Paro on Medium]]></title>
        <description><![CDATA[Stories by Christian Paro on Medium]]></description>
        <link>https://medium.com/@christian.paro?source=rss-ab2198bcff5f------2</link>
        <image>
            <url>https://cdn-images-1.medium.com/fit/c/150/150/1*p8HaKheAaeYa7oUVkf1l1g.jpeg</url>
            <title>Stories by Christian Paro on Medium</title>
            <link>https://medium.com/@christian.paro?source=rss-ab2198bcff5f------2</link>
        </image>
        <generator>Medium</generator>
        <lastBuildDate>Mon, 16 Nov 2026 23:13:11 GMT</lastBuildDate>
        <atom:link href="https://medium.com/@christian.paro/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[The One Place You’ll Find Actual Meritocracy]]></title>
            <link>https://medium.com/@christian.paro/the-one-place-youll-find-actual-meritocracy-27b37ca851a0?source=rss-ab2198bcff5f------2</link>
            <guid isPermaLink="false">https://medium.com/p/27b37ca851a0</guid>
            <category><![CDATA[culture]]></category>
            <category><![CDATA[tech]]></category>
            <dc:creator><![CDATA[Christian Paro]]></dc:creator>
            <pubDate>Mon, 07 Aug 2017 18:20:38 GMT</pubDate>
            <atom:updated>2017-08-07T18:20:38.503Z</atom:updated>
            <content:encoded><![CDATA[<p>…is in carefully-controlled competitive games.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/620/1*xsUPwaCecXmSzL7b8Il6pQ.jpeg" /><figcaption>this is what a fair test of merit looks like</figcaption></figure><p>Whether “meritocracy” is a good virtue to strive for <em>at all</em> is an interesting subject for debate. But all too often “this is a meritocracy” is used to excuse all manner of bias, toxicity, and inefficiency in defense of some incumbent group (who, yes, are usually a bunch of white men — and a particularly privileged and out-of-touch subset thereof).</p><p>So I’d like to point at something which actually is a meritocracy (in the popular sense of “the most talented and hard-working rising to the top” if not in the more-pedantic sense of “the most talented and hard-working making the decisions”) for the sake of comparison with “faux meritocracies” like tech and business.</p><p>Competition, like sports and games, which happens in an artificial environment where:</p><ul><li>the same rules are applied to everyone</li><li>these rules are clearly and openly defined</li><li>there is a “level playing field”</li><li>the required equipment is nearly universally available</li><li>coaching resources and opportunities for practice are nearly universally available</li><li>achievement is evaluated according to predefined criteria with clear rules for how actions or results are to be scored</li><li>no qualified player is barred from participating except as a result of a history of misconduct</li></ul><p>Importantly, these things are not true of all sports and games — and historically held in fewer cases than they do now because of things like segregated leagues.</p><p>For instance, an activity which is cheap or free for someone to get into (like track running, powerlifting, or chess) is going to be more universally accessible than one which requires expensive equipment or facilities (like hockey, golf, or polo). And game which contains a large element of chance may be “fair” without being “meritocratic” — the winners may not have started in a better position or done anything unfair, but they also may be the people who drew the right cards rather than the people who best played their hands.</p><p>But these activities can, by actively working to extend and equalize opportunity across potential participants, surface individuals of extraordinary talent while creating real suspense for spectators who aren’t going to know who’ll come out ahead before the game even starts.</p><p>When you look at something like software development, which is often <em>called</em> a meritocracy, you might wonder:</p><ul><li>are the rules applied equally to everyone?</li><li>how well do we, across our ranks, even understand what the rules are?</li><li>are we all trying to meet challenges of the same (or objectively-comparable) difficulty?</li><li>does everyone have easy access to the resources needed to get started?</li><li>does everyone have easy access to good coaches and skilled peers?</li><li>do we always know how our work will be evaluated, or that it will be evaluated consistently?</li><li>do we all know that we won’t be “filtered out” of hiring and promotion lists for arbitrary reasons outside of our actual ability?</li></ul><p>I know I’d go with a solid “no” on all of those except possibly the access to “the resources needed to get started”. And, on that, the availability of dirt-cheap computers and free online tutorials is a relatively recent phenomenon.</p><p>My own childhood was a real mixed bag as far as “privilege” goes, but I <em>did</em> have a computer in my house long before most of the people I knew because my grandmother (who still doesn’t use computers herself) had the foresight to know that computers were going to be important and somehow managed to pick up an IBM clone. I also had an office job in high school where, while I was technically in a low-level assistant/secretarial role (to be differentiated from the real departmental secretaries who seemed to know everything and everyone there), I ran across some discarded MS Access learning materials and picked up database design and VBA programming while being given free reign to automate away much of my own work. And while I remember when my parents will still retail grunts with a single community-college Associate’s degree between them, I also remember them taking their work home with them and discussing it with me as they climbed into HR and software development.</p><p>They are had a talent for finding opportunities for me to learn things which I didn’t have access to in my classes or the local libraries. I got a private tour of a university’s science wing when I was in grade school because of a conversation my dad had with a professor he met while training for a triathlon. Saw 3D printing when it was still just called “rapid prototyping with stereolithography” with a local inventors group they found a flier for. Got a ride to go to a DSP conference hosted by Analog Devices when I was still too young to drive (and was waved in for free by the registration people, who were excited to see someone there who was so young — and not being sent by their employer).</p><p>While working at Liberty Mutual I had the very good fortune of working under a young first-line manager (<a href="http://connectbiz.com/2014/11/deb-taylor-taylor-corporation/">Deb Taylor — she has an interesting story herself</a>) who now sits as the CEO of a large industrial company, and whose management style is something I’ve been clumsily trying to decode and imitate ever since I saw how effective it was at getting amazing results (and high morale) out of a team of odd and ordinary people. She also created an environment where I learned and accomplished a lot as a software developer despite not having any formal training or other developers present to learn from — instead I got a lot of practice with the business and human side of software, and a chance to see how someone can effectively mentor someone in a specialty they don’t themselves know much about if they know how to ask the right questions.</p><p>And that’s all before I went to university or become an “official” software developer.</p><p>I look around the “tech industry” and I see people who were basically born onto a railroad to success. I see people who probably worked 2x or 3x as hard as I did to get to the same place. People who got one big break and made good use of it, and people (like me) who got a lot of smaller breaks along the way which all added up to something big. People who go into a rage if questioned because they’ve never had to deal with any real criticism or critique, and people who are used to being second- and third-guessed on their every move.</p><p>I see a lot of in-group/out-group politics. A lot of attitudes which are meant to signal that a company “only hires the best” but in practice are just a pile of arbitrary filters and restrictions which probably have resulted in a <em>lowering</em> of overall merit or else an inability to effectively hire. This weekend some kid at Google published a pile of quasi-intellectual drivel about women not belonging in the industry, and next weekend there’ll probably be something else to be sad or angry about. Because this industry — especially the shiny “startup” scene that gets the lion’s share of the attention — is grossly immature, loaded with externalities much like those which have repeatedly driven bad behavior in the financial industry, and a magnet for people who don’t get that tech is supposed to serve society rather than the other way around.</p><p>One thing it is not is a meritocracy. It could be made a closer approximation of one, though, if we:</p><ul><li>make sure the rules are clear, published, and evenly enforced</li><li>…including responses to fouls and unsporting conduct</li><li>open up information on how career progression works so it’s not a game of “who knows who”</li><li>get a computer lab and qualified software-development coaches in every high school — same as they have tracks, weight rooms, and football coaches</li><li>open up our conversations about how performance is evaluated and rewarded — laying bare and inconsistencies across members of the team or between the espoused and actual values of an organization</li><li>have some real discussions about our work and how “good at typing code into an editor” is hardly the end-all-be-all factor in our overall organizational impact</li><li>get rid of hiring criteria like credential auto-filters (which sort on pedigree more than merit), and goofy “beer test” style culture-fit hoops (which are a better-suited for social clubs than for organizations which exist for the purpose of getting things done)</li></ul><p>…and that wouldn’t be a bad thing.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=27b37ca851a0" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Organizational Adaptations to Stress]]></title>
            <link>https://medium.com/@christian.paro/organizational-adaptations-to-stress-1c72ca9ba0c1?source=rss-ab2198bcff5f------2</link>
            <guid isPermaLink="false">https://medium.com/p/1c72ca9ba0c1</guid>
            <category><![CDATA[organizational-culture]]></category>
            <category><![CDATA[antifragile]]></category>
            <dc:creator><![CDATA[Christian Paro]]></dc:creator>
            <pubDate>Tue, 01 Aug 2017 20:39:43 GMT</pubDate>
            <atom:updated>2017-08-01T20:39:43.987Z</atom:updated>
            <content:encoded><![CDATA[<h3>Organizational Adaptations to Stress (Part 0: Definitions)</h3><p>An organization can thrive under stress if it has the culture, structure, and resources necessary to adapt to the stresses it will face.</p><h3>This Is Part of a Series:</h3><ul><li>Part 0: Definitions</li><li>Part 1: Fragility [Work in Progress]</li><li>Part 2: Robustness [Work in Progress]</li><li>Part 3: Resilience [Work in Progress]</li><li>Part 4: Antifragility [Work in Progress]</li></ul><h3>Four Levels of Adaptation to Stress</h3><p>These correspond to the remaining parts of this series, where I will approach the “evolution” of an organization through these levels in more detail.</p><h4>Fragile</h4><p>A fragile system is one which can fail suddenly under stress. Fragility is less about a system being “weak” than it is about it being brittle. It is vulnerable to total failure when stressed beyond some threshold. Until it reaches that failure point, though, it may not show any degradation at all.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/250/1*eyvMclYjJJxLOqcAxBCNUg.jpeg" /><figcaption>one robot’s foot away from being a cloud of dust</figcaption></figure><p>Fragile systems may be:</p><ul><li>non-adaptive, retaining a rigid structure and set of behaviors until failure, or</li><li>negatively-adaptive, becoming more brittle and susceptible to sudden failure when stressed</li></ul><p>Hard, brittle things like crystals can withstand stresses without yielding to them. That is, until the stress becomes strong enough or hits them at weak enough a point for them to break apart.</p><p>A pathologically-rigid bureaucracy may present a similar appearance of strength and order. But when it faces an unanticipated challenge, it more often than not will fail.</p><p>Rubber bands and paper clips yield to stress and can be restored to their original state. <a href="https://en.wikipedia.org/wiki/Fatigue_%28material%29">But over these cycles their structure weakens, which can lead to sudden failure</a>.</p><p>Negatively-adaptive organizations are common. One such pathology is an organization which has one or more “essential” people. These people take the brunt of stress-inducing events and do not have enough time to recover. Nor do they have support in getting others to help reinforce the areas they are covering. These overloaded individuals eventually burn out and exhibit “toxic” behavior or diminished performance. This can, in turn, disrupt the organization as a whole.</p><h4>Robust</h4><p>A robust system is resistant to failure under stress. It also fails in a gradual or “graceful” manner rather than as an abrupt critical loss of functionality.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/250/1*vmp0wW2UJFcUZzwBfziAJQ.jpeg" /><figcaption>tough, but sometimes requires repairs</figcaption></figure><p>Robust systems often have redundancies which allow them to operate even if some part has been damaged or lost. In some cases these redundancies allow for uninterrupted operation at full capacity. In others the system may lose some functionality or need some time to recover, but it remains useful.</p><p>Most “highly-available” computer systems are robust in this manner. The designers of these systems avoid having only one of anything. They also put mechanisms in place to redirect work to components which are in full working order.</p><p>You can find other examples of robust systems in contexts like how we get from one place to another:</p><ul><li>cars can run in a “limp mode” when some of their components stop working</li><li>trailers have redundant tires so they can make it to a service location after the failure of a single tire</li><li>run-flat tires can ride for limited distances on stiff side-walls after a loss of air pressure</li><li>subway commuters can switch from a stalled line to another line where lines have redundant paths</li><li>planes can make a safe landing after an engine has failed when they have more than one engine</li></ul><p>When people talk about an organization’s “<a href="https://en.wikipedia.org/wiki/Bus_factor">bus factor</a>”, they are referring to a form of robustness.</p><p>In <a href="https://en.wikipedia.org/wiki/Scientific_management">Tayloristic</a> management philosophies, “redundancies” are something viewed as a target for cost-cutting. But pursuit of that efficiency comes at the cost of organizational vulnerability. When one of its members leaves or suffers a temporary drop in individual output, the organization will have no one else ready to pick up their load.</p><p>Much like those “high-availability” computing systems, robust organizations have people with overlapping capabilities. They also do not push for everyone to be 100% utilized at all times. Doing so leaves little “headroom” to handle bursts in workload or cover for an absent member of the team.</p><p>Another form of organizational robustness comes from having well-prioritized objectives. When stressed, the organization can then divert resources to its primary objectives. For instance, if a lot of people are out on vacation, an organization with clear priorities can tighten its focus until they are back.</p><p>Robust systems will still ultimately fail unless repaired through outside intervention. The central decision-making of top-down structures becomes a bottleneck in addressing this damage. This creates a risk of enough damage to accumulate for the system to still reach a point of total failure. On the bright side, this will at least be a <em>gradual</em> failure rather than a sudden one as in the case of fragile systems.</p><h4>Resilient</h4><p>Resilient systems are those which, when stressed, eventually recover to their original state.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/250/1*GX8421jpdaavkpSAmRdSKQ.jpeg" /><figcaption>time heals all wounds</figcaption></figure><p>These are often extensions of robust systems. Like a robust system, they have redundant parts and gradual failure modes. The difference is that resilient systems can repair themselves as a basic reflex.</p><p>Some resilient systems are build around their desired state being a “minimal energy” state. Think of a pool of water. Disturb it as you will, it will return to its original shape. Any other shape would be unstable, and these instabilities lead it over time to go back to being flat and still.</p><p>Another form of resilience is what we call “healing”. The system captures outside energy and uses it to restore itself to its desired state. This behavior is anti-entropic, and only works in the case of an open system which has access to an external energy source.</p><p>Organizations can use internal corrective feedback to recover when they drift off-course. A profitable or well-supported organization can heal itself after many costly setbacks.</p><p>I’ll speak to the specifics in a later part of this piece, but the general requirements for resilience in an organizational context are:</p><ul><li>frequent or continuous monitoring of the organization’s current state</li><li>a clear understanding of the organization’s desired state</li><li>a clear understanding of how the organization’s actions affect its state</li></ul><h4>Antifragile</h4><p>Antifragile systems exhibit positive adaptation in response to stress. That which doesn’t kill them, makes them stronger.</p><p>If you are looking for a whole book on such systems, <a href="https://www.amazon.com/Antifragile-Things-That-Disorder-Incerto/dp/0812979680">Nassim Nicholas Taleb wrote one</a>.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/250/1*EmiRc9FZTijW8UOWzElkkw.jpeg" /><figcaption>a deliberate use of stress to elicit positive adaptation</figcaption></figure><p>It’s hard to find “antifragile” systems which aren’t “alive”, made of living things, or made by living things. But we can look at our human world for examples:</p><ul><li>Immunity to disease develops through exposure to disease. Vaccinations use controlled exposure to a pathogen to trigger immunity to that pathogen.</li><li>Weight training is a practice of stressing our bodies to make them stronger.</li><li>Emotional resilience develops through experiencing and processing emotional stress. For an extreme example (and very good read) see “<a href="https://www.amazon.com/Mans-Search-Meaning-Viktor-Frankl/dp/080701429X">Man’s Search for Meaning</a>” by Viktor Frankl.</li><li>Arms races show adversarial parties improving their offensive and defensive capabilities in turn. In some cases the “defensive capability” is actually the threat of a counter-offense.</li></ul><p>In all such cases, two thresholds are important to adaptation:</p><ul><li>The stress must be severe enough to stress the system’s recovery capabilities.</li><li>The stress cannot be so severe that the system cannot recover from it.</li></ul><p>To pick on the weight-lifting example, it would do me no good to go to the gym and exercise with two-pound dumbbells. Nor would it be beneficial for me to do max squat and deadlift attempts on a daily basis. The first would be too little stress, the second would be too much. This is relative, of course. There are people for whom those two-pound dumbbells can be a useful step in physical therapy. And people who would use my max lifts as warm-up sets on a light day. Their stress thresholds will be different from my own.</p><p>For an organization, antifragility comes into play when it:</p><ul><li>Reinforces stressed areas to increase the stress they can handle.</li><li>Has effective learning mechanisms for improving its structure and process.</li></ul><p>And now, on to a more detailed look at things which can make an organization fragile…</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=1c72ca9ba0c1" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Strategic Technical Debt]]></title>
            <link>https://medium.com/@christian.paro/strategic-technical-debt-b03fcd3b7c0e?source=rss-ab2198bcff5f------2</link>
            <guid isPermaLink="false">https://medium.com/p/b03fcd3b7c0e</guid>
            <category><![CDATA[software-development]]></category>
            <dc:creator><![CDATA[Christian Paro]]></dc:creator>
            <pubDate>Wed, 26 Jul 2017 23:55:38 GMT</pubDate>
            <atom:updated>2017-08-03T07:29:46.417Z</atom:updated>
            <content:encoded><![CDATA[<p><em>This is an opinion piece, on a matter which other people have their own strongly-held opinions. I would suggest also reading </em><a href="http://wiki.c2.com/?WardExplainsDebtMetaphor"><em>Ward Cunningham’s explanation of his own interpretation of the “technical debt” metaphor</em></a><em> and </em><a href="http://ronjeffries.com/articles/015-11/tech-debt/"><em>Ron Jeffries’ criticism of the metaphor</em></a><em> and its implication that there are valid reasons for temporarily cutting corners in software development. Obviously, I feel differently about this from Ron, but I also feel it’s often wiser to read a few contradictory perspectives on a matter and work out what applies to your own situation than it is to limit yourself to whichever perspective you first come across.</em></p><h3>What Is Technical Debt?</h3><p>Any decision made in the course of building or maintaining a system which yields some near-term benefit at the cost of:</p><ul><li>leaving work which still needs to be done eventually (the “principal”)</li><li>incurring an additional upkeep cost until the deferred work has been done (the “interest”)</li></ul><h3>How Could That Possibly Be a Good Thing?</h3><p>One of the things I think is responsible for the sharp splits in opinions about whether there is such a thing as “good” technical debt is that some of us have experienced it primarily in contexts where it is taken on because of ignorance or carelessness while others have seen it more often in contexts where it is employed intentionally as part of a work-prioritization strategy.</p><p><a href="https://martinfowler.com/bliki/TechnicalDebtQuadrant.html">Martin Fowler had some things to say about this</a>:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/512/1*nuJA9F7QOTmYGSMkGbswiA.png" /><figcaption>Martin Fowler’s “Technical Debt Quadrant”, see his article for the details</figcaption></figure><p>Ward Cunningham’s assessment seems to be oriented more to the “prudent” side of this quadrant (on the idea that everything which was done either was a good idea at the time or at least seemed like a good idea at the time), while Ron Jeffries’ assessment seems to be oriented more to the “reckless” side of the quadrant (on the idea that technical debt seems to disproportionately come from “cowboys” who have little concern for structure or quality).</p><p>I’ve seen all of the above, and have been responsible for instances of all of the above at one point or another.</p><p>Going on the “debt” metaphor, though, let’s apply that same quadrant to financial decisions:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/512/1*LfrJySduAJW6fS4SS2zZQQ.png" /><figcaption>A shameless knockoff of Fowler’s chart</figcaption></figure><p>Not <em>exactly</em> the same thing (all non-trivial abstractions, this one included, <a href="https://www.joelonsoftware.com/2002/11/11/the-law-of-leaky-abstractions/">leak at least a little</a>), but it does illustrate that the metaphor works in that there debt can be accumulated because:</p><ul><li>not taking the debt on has an opportunity cost which outweighs the cost of the interest on the debt (deliberate/prudent)</li><li>shit happens, sometimes without warning, and the debt is either a direct result of this or the best path forward — but is now one more thing that you need to take care of (inadvertent/prudent)</li><li>the debt is convenient for now, and you can’t be bothered with thinking about the future (deliberate/reckless)</li><li>the debt is the result of not paying attention to or fully understanding the consequences of your present decisions (inadvertent/reckless)</li></ul><p>To Ron’s point, a lot of the technical debt in most systems comes from reckless actions — making it the technical equivalent of taking on an irregular mortgage assuming that the housing market can only go up or maxing out credit cards to buy things you can’t afford and could easily do without.</p><p>But there’s also technical debt that’s a result of things which simply weren’t known at the time a decision was made (like a system having a design which is a good fit for the original intended use case — but a poor fit for the emergent use case it ended up being applied to). And technical debt which isn’t much of a choice because there are even bigger problems which need to be solved right now (an ugly patch to temporarily fix a production scaling problem can be a lot like putting a car repair or medical bill on a credit card because you didn’t think you were going to run into that expense so soon and didn’t have sufficient liquid resources to take care of it properly when it happened). These are reasonable situations which reasonable people get into, and fit into a general strategy of “accept and pay down” where there’s not much to do other than to recognize that it is impractical to completely avoid such debts and make sure you have enough resource to spare in the long run to pay them down before the costs associated with them snowball to an unmanageable level.</p><p>There is also technical debt which is incurred while paying off some other, even more expensive technical debt. Think of the next time you see a refactoring effort which goes through a few also-less-than-ideal iterations as “technical refinancing” where the new technical debts are (hopefully) at least fewer in number or lower in cost than the ones for whose elimination they were incurred.</p><p>Finally, there’s the kind of technical debt that I’m talking about for the rest of this piece, where you knowingly take it on because it allows you to move faster or sooner on something which would have a huge opportunity cost if you <em>don’t</em> employ debt strategically to be able to move faster or sooner than you otherwise could.</p><p><em>As an important note, which some of you may already have been saying to yourself while reading this, it’s easy to be wrong about what kind of debt you’re taking on. Sometimes a “prudent” action still fails to work out — you could go to university and have trouble finding work in your field of study, you could take on a personal loan to launch a small business and find that the market you were counting on didn’t really exist, and you could charge those car repairs and find that the income you were counting on for the next month didn’t come through after all. The good news, with respect to technical debt, is that it’s easier to “default” on in such cases than financial debt. More on that later.</em></p><h3>How Does This Work?</h3><p>When thinking about intentionally incurring technical debt, the following four questions are what I see as key to determining whether that debt would be “reckless” or “prudent” debt:</p><h4>What is the Opportunity Cost?</h4><p>For technical debt to be worth taking on, there must be something of value which you can get by incurring it.</p><p>Taking a $10K cash advance and putting it in a shoebox wouldn’t make much sense. Taking that $10K and putting it into starting a hosting company which could bootstrap your way into being the founder of a successful cloud provider at least makes the risks and costs something worth considering. While I don’t believe any credit-card cash advances were involved, <a href="https://www.wired.com/2015/05/amazon-isnt-one-killing-cloud-computing/">I do know someone who essentially did just that</a>.</p><p>At DigitalOcean, later on, the company would use credit lines to fund hardware build-outs rather than artificially slowing its rate of growth so it could wait for the old servers to pay for the new (rather than buying the new servers and letting them pay for themselves in short order) or diluting equity which was rising in value at a rate much faster than the equivalent interest cost on the credit lines.</p><p>Not taking on that debt would be very expensive. So the remaining questions became relevant.</p><p>On a technical level, the equivalent is a situation where you know that if you try to do everything according to “best practices” you’ll:</p><ul><li>be late to market — weakening your competitive position,</li><li>delay the delivery of some real business value (like cost savings from introducing a better inventory-planning or delivery-optimization system),</li><li>…or burn through your project’s or company’s funding before you get anything working at all.</li></ul><p>In these cases, technical debt is at least worth considering because there are real costs in <em>avoiding</em> it.</p><h4>What is the Interest Rate?</h4><p>Okay, so you know that there’s a big opportunity that you can only take advantage of if you also take on some debt…</p><p>…what is the debt going to cost?</p><p>There are a lot of things that are worth financing at a 3% APR which wouldn’t be at a 20% APR. Or even a 6% APR.</p><p>For instance, a house is often worth buying at a 3% APR, if you are confident that you’ll be staying in one place for a while, because that interest rate is:</p><ul><li>not far off from the average rate of appreciation for real estate over long time scales</li><li>tax-deductible, making it effectively even lower</li><li>an enabler for applying some portion of what you used to spend on rent to what amounts to savings in the form of home equity</li></ul><p>Buying a house at typical credit-card interest rates, however, would be insane — the overall cost would outweigh the costs of simply renting, while losing the relative flexibility of being a renter.</p><p>Technical debt, unfortunately, rarely has a nice “interest rate” number stamped on it to tell you exactly how many person-hours it’ll consume in a given time period. But you can get a feel over time for which shortcuts come a small cost and which come at a dear one. I’d hand-wave it as follows:</p><ul><li>Bad architecture is like payday-loan debt. Avoid it if at all possible, because the costs of fixing bad architecture are insanely high. This goes double if you’re talking about a 24/7 service with active users where you can’t “fix” the bad architecture by building a nicer version of the product from scratch and then replacing the old one wholesale.</li><li>Bad documentation is like credit-card debt. It’s okay in some circumstances, but should be paid off soon after it is incurred or else the costs associated with it will compound and make it hard to catch up with. If you pay it down soon enough (while the project is still fresh in your mind and you haven’t had to on-board any new maintainers) you might be able to get away without paying any “interest” at all.</li><li>Bad tests are like personal loans. Having tests which are both robust in their coverage and automated such that they can be easily run is cheaper over the long run than having only spotty test coverage or only manual testing. But ad-hoc manual testing can work surprisingly well where necessary to defer the costs of actually writing a full battery of automated tests — with the downside of adding to the cost of applying any update to the code. Unlike sparse or bad documentation, there’s rarely any “free” period where not automating tests has zero cost — you will probably find bugs once you get those tests together which would have been cheaper to fix if you wrote those tests right before or right after the corresponding product code.</li><li>Bad code is like a car loan. The costs of ugly, un-refactored code are real but often less than the costs of having no tests, shoddy tests, or only manual testing. Having ugly code does slow down maintenance and troubleshooting efforts, but often not as badly as missing/inaccurate documentation or a test suite that no one really trusts to validate that a change can sanely be deployed to production.</li><li>Deferred “features” which are really developer conveniences are like a mortgage. It’s good to check these things off and pay down this “debt” over time, but the costs are low and the opportunity cost of not releasing a product until you have beautifully-convenient development and deployment tools can be quite high. These items are often best addressed after feature work and avoiding/repaying the above forms of tech debt, and after applying this like of thought as a sanity check:</li></ul><figure><img alt="" src="https://cdn-images-1.medium.com/max/571/1*eGXW9bxRyxdA21uJRPtwkw.png" /><figcaption><a href="https://xkcd.com/1205/">XKCD #1205</a></figcaption></figure><p>There are probably a lot of people who would take issue with my feeling that documentation debt is worse (unless paid off very quickly) than testing debt or code debt. My take on the matter is that good documentation helps with the writing of good tests and good code, and that bad documentation can drive a misunderstanding of the system which leads to fundamentally-flawed design decisions in a way that substandard tests and code can not. That documentation can also be the guidepost for making sure testing and coding debts don’t get buried and forgotten — it’s easier to pay off the testing debts when the docs are in good shape, same as it’s easier to pay of the coding debts when the tests are in good shape.</p><h4>What are the Risks?</h4><p>Okay, so the opportunity looks good and the costs seem manageable.</p><p>What could go wrong with the opportunity, leaving you with nothing to show for the debt other than the costs associated with it?</p><p>What could go wrong with the costs which might make that debt more expensive than you’re expecting it to be?</p><p>How likely are these things? Are they things you’d be able to see coming in advance? Is there anything you can do to manage or hedge against them?</p><p>Examples of opportunity risks:</p><ul><li>The project fails to reach completion anyway, due to some other technical problem</li><li>The project fails to reach completion anyway, due to a retraction of support from the organization (politics, changing priorities, etc.)</li><li>The project is successful, but the resulting product or system fails to show the expected value (the market didn’t buy into it, the expected cost savings didn’t materialize, etc.)</li><li>The project is successful, and generates revenue or cuts costs — but the revenue ends up being cannibalized off of an existing product or new costs show up elsewhere in the system as an indirect result of the changes which were made</li></ul><p>Examples of cost risks:</p><ul><li>The resource expected to be available for paying off short-term technical debts fails to materialize — turning them into long-term technical debts</li><li>The team needs to increase its rate of growth and on-board a lot of new developers, who will have a harder time working with the system while those debts are unpaid</li><li>Deferring test automation allows a critical flaw in the system to go unnoticed because the manual ad-hoc tests were not reviewed as rigorously as automated tests would be, causing expensive-to-fix problems shortly before or even after the software is released</li><li>Careful design is deferred by creating a temporary system which is meant to be replaced on the “<a href="http://wiki.c2.com/?PlanToThrowOneAway">plan to throw one away</a>” principle — and the “temporary” system ends up becoming a permanent one</li></ul><p>As far as risk-management strategies go, one of the simplest is to limit how much outstanding technical debt can be incurred before some of it has to be paid off. In practice, there’s an inherent limit at the point where you can’t get anything else done because you’re spending all of your time dealing with technical-debt-related maintenance headaches. But ideally you can account (formally or informally) for how much time is being “wasted” on technical-debt related work or slowdowns — and use that as a gauge for when the team needs to have time explicitly allocated for documentation, test automation, code refactoring, or whatever else is needed to bring those costs back down to an acceptable level.</p><h4>What Happens in the Case of Default?</h4><p>This is one of the fun points about technical debt (as opposed to the financial variety).</p><p>Most of the time, if the opportunity side of the equation doesn’t work out, the debt can be cancelled without repayment — and no one is going to have a problem with this.</p><p>If you incur a lot of technical debt early on in a project which is then cancelled because of a priority shift or poor reception in early market testing, you can count it as a list of things you <em>didn’t</em> waste time on. Unless you incurred some of that technical debt while altering something which will remain in service, all repayments and “interest” costs are cancelled along with the project.</p><p>So, in the case of projects with a high market-fit risk, technical debt can be used almost as an option strategy where you can abstain from paying for most of the project unless the additional information you gather while market testing it confirms that the opportunity side of the equation is looking good.</p><p>That does, of course, rely on your organization being one which won’t try to rush people on to the next project after the beta is launched without giving them time to cross off any high-cost or high-risk TODOs that they had deferred while putting together an MVP to test the product’s viability.</p><p>Also, if technical debt <em>was</em> incurred in something which doesn’t go away along with the failed project, that cost will still need to be paid off. Which is a good reason for being more careful about what is considered “acceptable debt” in an existing system than you are with the unproven prototype you’re fitting into that system. And to make sure resource is going to be available to clean up anything which is hacked onto those systems (either by going back to do things nicely or by rolling back any hackish changes) even in the case of the project being cancelled.</p><h3>What Do I Need to Look Out For?</h3><p>There are some human factors which can make even deliberate and reasonable employment of technical debt difficult to employ constructively:</p><ul><li>Developers are often irrationally optimistic about their own work, which can make getting an <em>accurate</em> assessment of project opportunities, costs, and risks difficult.</li><li>Developers are often unfairly critical of other developers’ work. By this, I mean that <a href="https://en.wikipedia.org/wiki/Fundamental_attribution_error">they tend to overlook the context within which other developers have made decisions</a>, and instead judge those decisions as examples of what those developers would be capable of doing if not forced to make trade-off decisions as a concession to the realities of getting software out the door. Today’s strategic technical debt is tomorrow’s “incompetence” or “cowboy coding” when someone new sees the tech debt in the end product before understanding why these decisions were made. <em>I’ve been on both ends of this, myself, and can say it’s frustrating for everyone involved when the historical background of decisions is lost.</em></li><li>Sometimes a decision which seemed like a good idea at the time was a good idea at the time — and sometimes it only seamed like a good idea because critical information was not yet available. Because of this, some technical debts which were expected to be low-cost or short-lived end up lasting longer and costing more than they should. In an organization with a healthy learning culture, however, this can at least be used as a learning point around why these costs were misestimated and whether there were any blind spots which can be better covered the next time such a decision comes along.</li><li>Management’s focus and incentive structures rarely put much value on “niceties” like cleaning up scaffolding and temporary patches once the user-visible features have been shipped. So technical debt should be approached with extreme caution unless management is not actively involved in the process of making these decisions and aware of the necessity of paying off technical debts incurred in the implementation of a successful product.</li></ul><h3>Summary</h3><p>Technical debt can be your friend, if used consciously and with care in making sure the organization will be both able and willing to pay it down on a sane schedule.</p><p>That said, it’s still something best avoided if you can’t make a sane argument based on what you’ll be able to get by taking it on and what costs and risks will come with it until it is “paid off”.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=b03fcd3b7c0e" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Writing Code for Humans]]></title>
            <link>https://medium.com/@christian.paro/writing-code-for-humans-25b5072144b6?source=rss-ab2198bcff5f------2</link>
            <guid isPermaLink="false">https://medium.com/p/25b5072144b6</guid>
            <category><![CDATA[software-development]]></category>
            <dc:creator><![CDATA[Christian Paro]]></dc:creator>
            <pubDate>Sun, 23 Jul 2017 21:00:13 GMT</pubDate>
            <atom:updated>2017-08-03T07:27:29.136Z</atom:updated>
            <content:encoded><![CDATA[<h3>Writing Code for Humans — A Language-Agnostic Guide</h3><p>…because code which people can’t read and understand is easy to break and hard to maintain.</p><p>…and because there are a lot of style guides for writing code in specific languages (which are totally worth reading if you’re using one of those languages), but surprisingly little about writing code for humans outside of a few classic books on the subject.</p><p><em>This piece is inspired by </em><a href="https://twitter.com/mdlayher/status/888528672495456257"><em>a tweet about code not being “self documentin</em></a><em>g” from a friend and former co-worker at DigitalOcean (</em><a href="https://medium.com/u/9c4b364e2944"><em>Matt Layher</em></a><em>), and a follow-on question from </em><a href="https://twitter.com/CatSwetel">@CatSwetel</a> <em>on my +1 on that statement about whether I had a post or talk about this. Well, now I do. And you should follow these people — Matt is an extremely talented developer who regularly makes useful contributions to both DigitalOcean’s software infrastructure and Go’s open-source ecosystem, and Cat is a technically-oriented executive consultant whose insights into engineering practice are what I _wish_ “agile consulting” looked like as a whole.</em></p><h3>Maintenance Matters</h3><p>I’ve seen a lot of stats thrown around for the cost of software maintenance relative to the cost of development. In practice, most of the work I’ve done or been around has spent far more time on things like:</p><ul><li>feature enhancements</li><li>bug fixes</li><li>refactoring</li><li>solving scaling problems</li></ul><p>…than it has on building the first working version of a given system.</p><p>Some of what you will write is truly “disposable” code, which you write once, run once, and then throw away — but most developers spend most of their time on software which last long enough to require some form of maintenance. Big, important projects (the kind that tend to have words like “system”, “infrastructure”, “library”, or “framework” in their descriptions) will skew especially far toward the side of maintenance costs vs. initial development costs. And, while back-office business-logic code and front-end interfaces tend not to require the same kind of long-term <em>technical</em> maintenance, they are prone to requirements changes even after they’ve been happily running in production for months or years.</p><p>Also, it’s hard to guess just how temporary a “temporary” system will be. I’ve seen code that was meant to last forever get tossed a quarter after it was written — and have been personally responsible for a handful of quick “hacks” that were meant to serve as short-term patches while working on a proper long-term solution which never came because of changes in priorities. Sometimes a bigger problem or opportunity comes along. Sometimes the hack works well enough that there’s not much incentive left to spend 10x the resources on something that’ll solve what’s essentially an already-solved problem.</p><p>So it’s safest to assume that nothing that makes it past the day you wrote it is immune from needing someone to go in and work on it later.</p><h3>Cleverness is Dangerous</h3><p>Nothing here that most developers haven’t already heard — but seeing how often developers (myself included) manage to forget this when writing things, it doesn’t hurt to reiterate.</p><p><em>If you think you just did something very clever, be very wary about whether it’ll cause maintenance headaches down the road.</em></p><p>Sometimes “clever” code is actually helpful, or even necessary. There are a handful of cases where that extra bit of performance or flexibility is actually useful for practical purposes. Usually, though, it’s more of a liability than an asset.</p><p>Even when that “clever” thing is done with good reasons for doing it, it should be:</p><ul><li>In an abstraction that makes it so no one has to worry about how it works unless working directly on that specific “clever” part of the code. (For example, you might have a neat logging or tracing trick which uses some ugly reflection hacks to help gain some visibility into the code — but nothing making use of it should depend on how it works and nothing other than the trace output should depend on it working at all.)</li><li>Heavily commented with explanations of both how it works and why this approach was chosen over something simpler/safer/more-obvious.</li></ul><p>If you can’t explain how the “clever thing” works in simple terms, you probably don’t understand it that well yourself. If you can’t explain why it’s necessary, it probably isn’t. If you <em>can</em> do both of these things, the nice documentation you attached to your clever new code can turn that code into a learning tool for other developers (and a concrete “notebook entry” for your future self) rather than a liability for the team.</p><h3>Code is Not (Always) Self-Documenting</h3><p>Sorry. It’s just not.</p><p>I first heard the claim of “self documenting code” in reference to the Linux kernel. I’ve dabbled in kernel hacking for fun and understanding, and did some more-substantial work with QEMU and LibVirt as part of a port to the s390x architecture while at IBM. And I honestly believe that the communities working on these projects would be larger, more effective, and perceived as more welcoming to new contributors if the commenting and documentation for these projects wasn’t so severely bare-bones.</p><p>The key here is that naming standards, formatting standards, and rigorous code review can do a lot to make sure there isn’t any line or block of code that someone reasonably familiar with the language can’t “parse” like a compiler and reason though — but that doesn’t solve for the problem of said person having to grep their way around the codebase and construct their own maps and notes when they want to see how it all fits together or why a thing does what it does.</p><p>In toy examples like people make in most academic programs that purport to teach you how to develop software (whether at a university, a 12-week bootcamp, or something in-between), this isn’t a very big deal. There’s not that much code to sort through, and many developers don’t even need to write down notes on their exploration while developing a mental map of the codebase.</p><p>In large projects (like operating-system kernels, databases, systems-management stacks, and a surprising number of business-back-office systems once all the actual rules of the preexisting human-based system have been discovered and incorporated), this exploration starts looking more like a dungeon crawl than the search for your hotel room after check-in. So, unless the point is to challenge people with rediscovering things that someone else already knows, it’s only sensible to hand your intrepid new explorer a decent map and some guidance on what the various artifacts and incantations in this strange place actually do.</p><h3>…But Names and Structure Go a Long Way</h3><p>While “clean code” doesn’t pass as a complete solution for “good documentation”, it does have a place in the overall picture.</p><p>If you need to put a comment on a line of code to say what it does, then that may be a sign that better naming or clearer structure would be helpful. For instance, there’s a reason for why in many languages you can express something like this:</p><pre>maskedValue = inputValue &amp; (1 &lt;&lt; 3 | 1 &lt;&lt; 1)<br>multipliedValue = inputValue &lt;&lt; 3</pre><p>…or like this:</p><pre>maskedValue = inputValue &amp; 10<br>multipliedValue = inputValue * 8</pre><p>In the first set, we’re helpfully showing that the mask has bits 4 and 3 set without making the user work that out backwards from a decimal representation of the mask — but we’re multiplying in a way which isn’t going to make as much sense to most users as the way shown in the second set of examples. In many cases, the compiler/interpreter will render these two examples to the same underlying behavior, so the difference isn’t for the computer. It’s for expressing intention and framing something in the way that’s most intuitive to the user.</p><p>On that front, wouldn’t it be even nicer to have something like this?:</p><pre><br>toCreate = 1 &lt;&lt; 0<br>toDelete = 1 &lt;&lt; 1<br>toRename = 1 &lt;&lt; 2<br>toShare  = 1 &lt;&lt; 3<br>toCopy   = 1 &lt;&lt; 4</pre><pre>mask(originalFlags, maskFlags) = {<br>  originalFlags &amp; maskFlags<br>}</pre><pre>canCopyOrShare(permissions) = {<br>  mask(permissions, toShare | toCopy) != 0<br>}</pre><pre>// ---- And, elsewhere... ---- //</pre><pre>threadsPerCore = 8 // TODO: Read from environment variable.</pre><pre>workerThreads = cpuCores * threadsPerCore</pre><p>The above code isn’t written in any real language (though it is a little C-like and a little Scala-like). But using meaningful names and a little structure, along with language syntax which hints at the actual intended semantics, helps to make the purpose and behavior of the two abstract “mask” and “multiply” actions clear.</p><h3>Explain Context and Purpose</h3><p>There’s an old saying where “comments are for saying why a thing is done, code is for saying how it is done”. <a href="https://blog.codinghorror.com/code-tells-you-how-comments-tell-you-why/">There’s also been plenty written about this before</a>.</p><p>Most of your comments should be explanations of why something is done:</p><ul><li>Why you implemented something in a non-obvious way.</li><li>Why you implemented something in a particular way, instead of some other plausible alternative.</li><li>Why you implemented something at all.</li></ul><p>The first of these explanations will likely save hours (or weeks) of people trying to figure out what you were thinking when you did something — because there, right next to where you did it, you told them exactly what you were thinking at the time. It can also prevent people from “fixing” something that might look off in the immediate context but is actually correct in some larger context. Ideally you don’t have too many cases of the latter — but like most things, working software implementations are rarely free of structural flaws.</p><p>The explanation of choices between alternatives can help quash future bike-shedding arguments about whether X should be replaced with Y. Or, it may be a declaration that you actually did just throw something in there without taking the time to explore all the alternatives — making an explicit acknowledgement of the fact that there may be a better way which just hasn’t been considered yet.</p><p>And the statement of <em>why</em> something was made in the first place helps to draw a path from low-level implementation details up into the architecture and/or out to actual stakeholders for whom the project exists. Not all developers care as much about the problem domain as they do about the solution domain — but others (among which I count myself) have a hard time making decisions about things without first knowing what the project is meant to accomplish, for whom it is being done, and how anything already present in the system fits (or fails to fit) into that big picture.</p><p>Beyond the “why” comments, I’m a big fan of high-level documentation which outlines:</p><ul><li>What parts a system is made of</li><li>How they fit together</li><li>Why, at a high-level, they exist</li><li>How, at a high-level, they work</li></ul><p>This documentation is what I think of as the “map” to your software. It provides a tool which allows new developers to navigate a system they haven’t had much time to become familiar with. It also gives long-time maintainers an organizational framework for their knowledge which can help them to manage problems and solutions of much greater scale and complexity than they could effectively work on with just a “mental map” of the system.</p><p>Often, this documentation will be a mix of generated docs (of the sort which gained popularity with Java and JavaDoc) and prose-and-diagram-based architectural specs or overviews. I like the idea of everyone working on a project having a shared picture of the system they are working on (ideally one they could sketch on a whiteboard without much structural variation across what each person would draw), and having an at-a-glance index into everything already present and available in the system.</p><h3>Highlight The Tricky Bits</h3><h4>TODO Tags:</h4><p>One of the examples above uses one of my favorite comments, the TODO tag:</p><pre>threadsPerCore = 8 // TODO: Read from environment variable.</pre><p>In this case, we gave our threadsPerCore a meaningful name instead of leaving it as a “magic number”. But we haven’t gotten around to making it configurable, though it is the sort of thing that probably should be at some point. So the TODO tag gives us something we can search for, make listings of, or get a count of as an idea of what “nice-to-have” items we would like to take care of at some point in the future.</p><p>If you’re thinking “hey, shouldn’t that be a ticket in a tracker instead of a comment buried in the code?”, I can get on board with that. But who said it was either/or?:</p><pre>threadsPerCore = 8 // TODO #1936: Read from environment variable.</pre><p>Now you have something that can point you to the issue you opened in the tracker, and something you can search for using the issue number when you get around to actually working on that issue. Whether someone sees the comment while working on something else, and decides to knock off the issue in a bit of slack time, or someone picks the ticket off the queue, neither is going to need to waste time looking for the other half of that equation.</p><h4>FIXME Tags:</h4><p>These are another tag which has become a popular convention. Like a TODO tag, they indicate that more work could be used on something. Unlike a TODO tag, they indicate that the work is needed not just as an improvement, but as a way of remedying something which is known to be broken.</p><p>There are some people who don’t think you should ever have these in a codebase. I am not one of those people. Instead, I see them as a useful tool for when:</p><ul><li>You are working on something which is not even pretending to be production-ready, and need a quick way to mark stuff that you know isn’t quite right yet.</li><li>You have some edge case that isn’t implemented yet, or where the behavior yielded is incorrect or undesired, but it’s not common or critical enough to stop progress on the project or shipment of a new feature until it is fixed. Sometimes shipping a 90% correct feature and coming back to fix that last 10% is better than not shipping one at all. There’s a judgement call to be made there, but one thing you definitely should not to is ship a 90% correct feature and then forget about the 10% that’s broken because you never wrote it down anywhere where you’d see it again.</li><li>The FIXME isn’t a behavioral bug, but is some piece of high-interest technical debt which should be addressed sooner rather than later because its presence is a noticeable drag on further progress on the product.</li></ul><h4>DRAGON Tags:</h4><p>Like the TODO and the FIXME, the DRAGON tag marks some bit of ugliness in your code which may need to be addressed in the future. Unlike them, it’s something where the relevance of addressing that problem is conditional on some other change or condition.</p><p>This tag is something I started using at DigitalOcean after realizing that I had NOTE tags and similar on a mixture of things which were good-to-know but not hazardous to be ignorant of and things which could bite you hard if you weren’t aware of them. So, for the sake of having something as highlightable, searchable, and countable as the TODO and FIXME tags, DRAGON was born with the implication of “here be dragons” and “be wary of waking the dragon”.</p><p>There’s <a href="https://twitter.com/pomeranian99/status/858856994438094848">an old story about how a missile was programmed with known memory leaks which would crash the guidance system if the program ran for long enough</a>. The developers responsible were okay with this, and consciously left the leaks in place because the rate of leakage was calculable, there was headroom to spare in the hardware for the leaked memory, and the missile’s range limitations meant that it was going to hit its target or run out of fuel — in either case self-destructing before the leak could cause a crash.</p><p>That would be an excellent (if extreme) example of where a DRAGON tag would be useful. There’s a “problem” which is known to not be a practical issue because of something the developers know about the context within which the program is used. It is, however, based on an assumption (about the limitations of the missile’s range) which may fail to hold true in the future. Imagine the same software being reused in a later generation of the missile which has a longer range. It would be a very helpful thing for the maintainers of this software to have a way to search for any cases of “stuff that works they way it should under the conditions of its current usage, but it brittle in a way that could make a seemingly-innocuous design change trigger an ugly failure mode”.</p><p>Like TODO and FIXME tags, DRAGON tags probably shouldn’t proliferate too much without someone taking the time to eliminate some of these cases altogether — a few such issues can be managed, but once there are enough that it’s hard to do a quick scan of them they can start to look like “noise” and be ignored or overlooked with nasty consequences.</p><p>That said, I’d much rather have a sign warning me about something “dangerous” in the code than an engineering culture which discourages people from marking their ugly hacks by picking on the markings rather than recognizing them as part of an overall QA system (which also includes testing, code review, visibility tools, and good tooling for gradual deploys and fast rollbacks) which can help to reduce the overall number and severity of production incidents.</p><h3>Test Your Documentation</h3><p>A funny thing about documentation is that it has a way of drifting apart from the reality of the system being documented. The further it is from the system, the worse this is. For example, comments on or adjacent to a line of code are <em>usually</em> updated when the thing they apply to is changed in a way which would invalidate them. Function-level comments are more easily missed. Class or file-level commends more easily still. External specs and overviews rarely remain accurate to the system they describe unless active measures are taken to keep them in sync (or code review disallows any changes which would violate the spec).</p><p>Documentation can also, like the code being documented, have bugs in it. Some are trivial, like spelling and grammatical errors which don’t change the meaning of anything but do look unprofessional or distract from the intended meaning. Some are serious, like a misstatement of the behavior of a component which can lead a developer to use it in a way which will <em>create</em> a defect in the software because the documentation has mislead them.</p><p>But, like code, documentation can be both reviewed and tested.</p><h4>Reviewing Documentation</h4><p>When doing code reviews, documentation should be part of the review.</p><ul><li>Does documentation exist where needed for clarity?</li><li>Is the “why” documentation accurate to the actual problem space and findings in comparing alternative possible approaches?</li><li>Does any “what” or “how” documentation match what the code actually does? If there is a summary of what some unit of code does, is the summary one which follows from the code’s actual behavior?</li><li>Do the high-level “map” documents actually point to the right places? Or do they have misspelled names, broken links, or references to the wrong thing (as can happen in copy/paste errors or as the occasional result of some mental mix-up).</li><li>Is there anything in the documentation which is confusing, ambiguous, or in need of further detail or better structure in order to clearly express the author’s intent?</li></ul><h4>Testing Prescriptive Documentation</h4><p>Prescriptive documentation (like “how-to” documents) is easy to test. Essentially, it’s the same thing as a test script as would be used for manual end-to-end testing, and it can be tested by handing it to someone who had little to do with making either the document or the system being documented to see if they can follow it and reach both the intended results and the intended understanding of what they did.</p><p>If they are confused, or ran into a dead-end because something in the doc didn’t work, they’ve found a bug in the document, the system or both.</p><p>Incidentally, passing such a document to a test-automation developer and having them use it (rather than the “white-boxed” code) as the basis for automating an integration or end-to-end test can similarly test both the doc and the system.</p><h4>Testing Descriptive Documentation</h4><p>Documents for things like interface contracts are a little less obvious to test, but I still feel they are testable by having these documents used as the basis for test automation rather than (or in addition to) writing unit tests with full knowledge of and access to the code being tested.</p><p>Different shops have different ideas on testing, but my thought here is that this is a good place to split up unit testing by having the feature developers write unit tests based on what they know about the code, and by having separate testers (who may or may not be dedicated QA engineers) write a battery of tests against the system <em>as it is documented.</em> The first set of tests can go for the areas the developers know are thorny from having done that development, while the second is probably a better simulation of actual usage given that most code is “used” most often by people who didn’t originally write it, are just calling it from elsewhere, and who read the library docs to understand how it works rather than reading the code itself.</p><h3>Summary</h3><p>For all the fights that break out over brace placement and how indentation is done, most of the human-friendliness of code comes from structure, naming, and documentation.</p><ul><li>Give things meaningful names</li><li>Put related things together, keep unrelated things separate</li><li>Keep the code simple wherever possible</li><li>Explain the code in friendly terms and why it was not done in the “obvious” way when something “clever” is necessary</li><li>Use comments to give context to why a thing exists and why it behaves the way it does</li><li>Use high-level documents as a map through which new maintainers can easily find a good starting point for troubleshooting and issue or introducing a new feature</li><li>Mark the scary and thorny bits of the codebase as such, both to encourage remediation and as a guard against people making careless modifications in areas of the codebase which may contain non-obvious hazards</li><li>Reviewing and testing documentation can be as important as reviewing and testing your code in a long-lived project; bad documentation can cause at least as many problems as bad code</li></ul><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=25b5072144b6" width="1" height="1" alt="">]]></content:encoded>
        </item>
    </channel>
</rss>