<?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 Vedran &quot;Brko&quot; Krizek on Medium]]></title>
        <description><![CDATA[Stories by Vedran &quot;Brko&quot; Krizek on Medium]]></description>
        <link>https://medium.com/@vedran.krizek?source=rss-7049746239c7------2</link>
        <image>
            <url>https://cdn-images-1.medium.com/fit/c/150/150/1*bHWmpd4pRprSUNXBNQQLaw.jpeg</url>
            <title>Stories by Vedran &amp;quot;Brko&amp;quot; Krizek on Medium</title>
            <link>https://medium.com/@vedran.krizek?source=rss-7049746239c7------2</link>
        </image>
        <generator>Medium</generator>
        <lastBuildDate>Tue, 17 Nov 2026 23:10:43 GMT</lastBuildDate>
        <atom:link href="https://medium.com/@vedran.krizek/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[Impact-driven development part 4: Layered requirements in agile contexts, requirements maintenance…]]></title>
            <link>https://medium.com/@vedran.krizek/impact-driven-development-part-4-layered-requirements-in-agile-contexts-requirements-maintenance-bef2ec0fa10b?source=rss-7049746239c7------2</link>
            <guid isPermaLink="false">https://medium.com/p/bef2ec0fa10b</guid>
            <category><![CDATA[requirements-engineering]]></category>
            <category><![CDATA[software-engineering]]></category>
            <category><![CDATA[product-management]]></category>
            <category><![CDATA[software-requirements]]></category>
            <category><![CDATA[agile]]></category>
            <dc:creator><![CDATA[Vedran "Brko" Krizek]]></dc:creator>
            <pubDate>Tue, 07 Apr 2026 10:43:07 GMT</pubDate>
            <atom:updated>2026-04-09T13:58:54.622Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*M0IHoZmWtniLyIqXQCAx9A.jpeg" /><figcaption>Here is a random photo of a moongoose, as you can’t get much more agile than those furry fellows.</figcaption></figure><h3>Impact-driven development part 4: Layered requirements in agile contexts, requirements maintenance and the conclusion</h3><h4>In the series so far, we’ve completed the main part of our journey to a deeper understanding of the requirements and their crucial and even foundational role in any project where more than one person is involved. However, we did leave a few loose ends and a couple of odd, unaddressed bits and pieces here and there. This final article in the series is where we take care of all of those, once and for all.</h4><h4>Also, this is where we finally apply what we’ve learned about requirements so far to the Agile context, and we also mention agentic engineering and post-delivery maintenance, so you might want to stick out for this one.</h4><h3>Layered requirements in lean and agile contexts</h3><p>So, you might be saying to yourself, “This all looks brilliant so far” (aww, thanks, you’re too kind…), “but it sure as heck sounds mighty waterfall-y to me.”</p><p>Well, it does, but that is more due to how we are accustomed to looking at the requirements and not because that is actually the case. We’re all conditioned to look at any standalone requirements document as a waterfall artifact, but that&#39;s nothing more than a misconception that we all picked up along the way—the difference between waterfall and agile requirements is not really about whether the requirements documentation exists or not or about the particular format it comes in, but rather about the level of detail.</p><p>Agile methodologies adopt a progressive, incremental, level-of-detail buildup for requirements, rather than “everything will be defined at the beginning,” inherent in waterfall practices. However, you still DO need to start with a complete end-to-end picture in an agile context as well, even if it&#39;s only a fuzzy or grainy one.</p><p>And when I say “end-to-end”, that is really ALL that I imply by the term, as <strong>those “ends“ with which you start in your first iteration do not have to be the same ends (and usually, if you do things right, they won’t be) that you’ll finish with</strong>, but they have to be functionally meaningful ends nevertheless.</p><blockquote>The big difference between agile and waterfall is in WHEN, and on WHAT SCOPE detailed discovery/design happens.</blockquote><p><strong>When ALL</strong> (or a significant majority of) <strong>design and discovery happen at the beginning of the project</strong>, and the requirements document contains all results of that process, <strong>we call that “waterfall”</strong>.</p><p>However, <strong>when design and discovery happen iteratively, just-in-time</strong>, and the resulting requirements are amended with new details or those details are documented in iterations themselves throughout the course of the project— <strong>that is what we call agile</strong> (or better yet, we should call that <strong>iterative</strong> because that is exactly what it is and Agility is “just” the ability to change direction between iterations, and is therefore an effect allowed for by iterativness of design and discovery in the first place).</p><p>All that famed agile collaboration, transparency, etc., you’ve heard so much over the last decade or so, happens as a necessary consequence/element of this iterative just-in-time discovery&amp;design. Those happen because they are an integral part of the discovery process, regardless of the underlying project methodology, and not because they are somehow magical inventions of the agile manifesto. Agile manifesto in effect merely describes what naturally happens when you design, develop, and deliver iteratively rather than in one “big bang” fashion, provided you follow good, common, widely adopted, and long-known engineering principles and practices.</p><p>If we want to be extremely pedantic (and a bit harsh and oversimplifying), we could say that the rest is just window dressing and some ceremonies, and that the only true and foundational difference lies in the distinction outlined above.</p><p>But even if we refrain from such opinionated statements, if the argumentation presented above stands, then the role of the requirements, and consequently, the layered approach to engineering them, is, and should be, the same in both cases.</p><p>Now that we&#39;ve got that out of the way, you might be wondering how to apply all that we’ve covered so far to your agile project.</p><p>The good news is that it applies seamlessly without requiring changes to how you approach sprints or implement your Scrum methodology (or any other agile framework).</p><p>The reason is that layered requirements engineering is a<strong> framework</strong>, which does not mandate or restrict project methodologies or contexts it can be applied to — if a methodology needs requirements (and if there is more than one person involved — they all do), layered requirements engineering will work out-of-the-box.</p><h4>Why should you even care?</h4><p>In my experience, most real-world approaches to creating agile requirements artifacts, such as product/project manifests and backlogs, are based on improvisation or misunderstanding of the ‘communication over documentation’ principle. The result is often incomplete and inconsistent, and as a result, estimation, planning, and ultimately, reliable value delivery are usually impeded. As an illustration, try to honestly assess when was the last time you were involved in a project where you gave the project manifest more than just a token attention and care, and where you didn’t (futilely) rely on scrum ceremonies as a solution to all your in-project woes?</p><p>Layered requirements engineering provides you with a consistent and structured way to create those artifacts, artifacts that you must create anyway — product manifest and backlog. The good part about it is that it does so without requiring any changes to your existing Scrum implementation.</p><p>Let’s illustrate all that with an example.</p><h4>Building a project manifest</h4><p>Every project needs a central document describing the high-level project context — in Agile, this is usually called “product/project manifest” (although its content, structure, and mere existence can and do vary <strong><em>wildly</em></strong> between projects).</p><p>The way to get a project manifest from your layered requirements is very simple — bordering on being trivial. You simply take the model layer, remove all goal statements except the top-level ones (also often called “epics”), and what you end up with is the manifest, complete with actors, high-level goals, and the project context. No changes or special approaches are required there.</p><h4>Building a backlog</h4><p>Now, let’s examine each actor-goal (story) and its individual sets of acceptance criteria, containing both “standalone” ones and those linking to particular formally described details.</p><p>When we do that, what we can observe is that what we have on our hands is a complete, well-formed PBI.</p><p>It has a goal that needs to be achieved, it has a list of important criteria that need to be satisfied, and every relevant detail is linked to via references in acceptance criteria — all standard elements prescribed by frameworks like Scrum.</p><p>In other words, you have a traceable, self-contained, fully implementable unit of work — exactly what the PBI should be. No changes or special approaches are required here either.</p><p>Now let’s try to meld all this together into a typical Scrum scenario.</p><h4>An illustrative Scrum scenario</h4><p><em>(Note that we’re focusing on requirements artifacts, in particular on manifest and product backlog, and we’re assuming all other ceremonies/events/techniques such as refinements. planning, story point estimates, etc., are implemented in a standard way):</em></p><p><strong>sprint 0: Creating the manifest and initial backlog (*)</strong></p><p>You build and document the model layer as described in this article, keeping actor goals on the “epic” level without “drilling down”. You now have your manifest (model layer) and your initial product backlog (epics).</p><p><em>(*) Sprint 0 can be a contentious point as there are some in the scrum community that fully embrace the principle and some who vehemently oppose it. The author of these lines personally doesn’t care about it either way, and so sprint 0 here is used to describe “work that happens before our first &#39;proper&#39; sprint with the implementation team” — nothing more than that.</em></p><p><strong>sprint 1+: Continuous discovery and delivery</strong></p><p>You select one or more epics, decompose them into stories (actor-goals), and proceed as described in this article to discover and define acceptance criteria and incrementally build the connected detail layer.</p><p>Now you have implementable PBIs in your backlog. Select a subset relevant to the iteration’s goal, and then implement and deliver it.</p><p>And there you have it, Scrum — done in the most standard way possible — but with meaningful, consistent, and well-formed requirement artifacts.</p><p>And you didn’t have to change a thing.</p><h4>The important difference between the product and implementation backlogs</h4><p>There is one additional point or a distinction I’d like to make, as I&#39;ve found that being oblivious to it seriously impedes the product owner’s ability to effectively steer and manage the iterative delivery process through its backlog.</p><blockquote>There are two distinct backlog types, both of which originate from the project model, predominantly from its functional part.</blockquote><p>The first is <strong>the product backlog</strong> — it is essentially the same as the functional model, as it is composed of PBIs, each of which describes one piece of the functional model (a.k.a. scope). This backlog does not capture broader project context, organizational constraints, team maturity, and skill level, etc. What it DOES capture is <strong>functional scope</strong>, and it does that extremely well.</p><p>However, you cannot really iteratively design and build a system just using this kind of backlog, unless you are in a very lucky position to have an extremely mature organization, team, and stable project context. And if you are that lucky, you don’t really need to worry, as things will work out in the end anyway, but for the rest of us, there is another backlog that is built just for that purpose, <strong>the implementation backlog</strong>.</p><p>Implementation backlog extends and augments product backlog in the sense that it contains all of it, with enough detail to reliably implement it, but it also contains additional, specialized PBIs that are there to specifically address and mitigate risks originating from organizational, team, and project environment limitations and particularities.</p><p>The typical (but not the only) example of such PBIs is SPIKE tickets used for research (tech. risk or team immaturity mitigation, etc.) or synchronization PBIs used for managing a disjointed project environment, etc.</p><p>Those eagle-eyed of you will notice that what I call implementation backlog looks suspiciously similar to the sprint backlog, one that results from the sprint refinement process, and that is true; they represent the same thing.</p><p>BUT there is an important difference there — as when thought only in individual sprint terms, the high-level picture often gets lost, and any spikes, research, and synchronization PBIs suddenly become “stranded on a sprint island”. What that means is that since they were discovered just before the sprint, and within a time-boxed ceremony, you have unnecessary limits on their proper design and elaboration simply due to time constraints that exist at that point in time.</p><p>You might say, “Yes, but we always have our backlog refined for at least 2 sprints in advance, so our sprints do not start right after the refinement session that addresses their scope”. Well, that is great (and now you finally know WHY that approach works), but also not very common in practice, especially for spikes and experiments, and you still have time constraints of refinement sessions in which you’d address two very conceptually different things — functional delivery and risk mitigation.</p><p>There are techniques to deal with that as well; “three amigos” sessions being just one of the many, however, you can just have implementation backlog proper right away and not awkwardly tiptoe to it with multiple good practices that are aimed at solving the effects of not having one in the first place.</p><p>The concept of implementation backlog, therefore, aims to decouple risk mitigation from individual sprint planning and free it, so to speak, to be considered independently throughout the project lifetime and not only during sprint refinement ceremonies. It also allows you to implement incremental, iterative delivery outside the formal Scrum framework in an educated way, rather than just cutting out bits you don’t find working in your organization without truly understanding why.</p><p>Additionally, this distinction clearly exposes (and forces you to deal with) two major Scrum “silent issues”. I’m talking about the magical, mythical being called a <strong>product owner</strong> that is supposed to somehow (now you know why that can never work) manage delivery just by prioritizing functional scope, and just-as-mythical <strong>self-organizing team</strong> that can somehow manage and address all those project environment issues as they appear.</p><p>Neither of these two exists “in the wild” in the vast majority of cases, so you need to address those issues and supplement needed expertise if you want to have any real measure of control over the delivery, and I find this concept of implementation backlog extremely illuminating and helpful for understanding this fact.</p><p>For example, for the product backlog, the project model is enough; however, for a <strong>good implementation backlog</strong>, you’ll need a product owner who deeply understands:</p><ol><li>engineering process itself</li><li>strengths and limitations of the implementation team and the organization itself</li><li>project context (that part is covered by the remainder of the project model — the context part)</li></ol><p>You can get someone who can do all that (business decisions, requirements engineering, and those items listed above), or you can split that role into multiple people — now that you know exactly which competences you need, instead of just one big and misleading “product owner owns backlog” statement.</p><p>In my experience, understanding this distinction and (more importantly) addressing it significantly improves the delivery management on any backlog-driven project, be it agile or simply iterative.</p><h4>Role of requirements in the era of agentic engineering</h4><p>If you wondered whether requirements still have their place in the era of agentic engineering, where it seems that all you need is an idea, a prompt, and the rest just comes out like magic, let me assure you that they do, and probably even more than you think.</p><p>First of all, if you truly think that all you need is “a good prompt,” you’re in for a rough awakening once you try to <strong>engineer</strong> anything non-trivial.</p><p>And second of all…</p><blockquote>The primary role of requirements does not change with the introduction of agentic engineering practices and will not change until there are at least two humans involved in the process of software design, implementation, and delivery.</blockquote><p>The reason is simple — the primary role of requirements is to create a mental model that can easily be shared between stakeholders, and that role is central and will remain to be central as long as humans are involved.</p><p>For implementation, though, well-defined, definition-of-ready-conforming PBIs are a prerequisite for reliable implementation and delivery (also see internal standards chapter a little later in this text), and that prerequisite does not change regardless of whether the implementation agent is a remote human or an “AI”.</p><p>I’ll illustrate this with an example — would you consider redesigning your whole requirements writing “game” if you were to add a remote developer (or three) to your implementation team?</p><p>You wouldn’t, right? (<em>If you think that you would or should, you might have a nasty problem with your engineering pipeline, and you really should go and see someone about that, but I digress...</em>)</p><p>My claim here is that adding coding AI agents to your implementation team — provided you are doing it correctly (see <a href="https://medium.com/@vedran.krizek/ai-augmented-software-engineering-41bd936d5978">this article</a> to get a better idea of what I mean by the term “correctly”) —should in no way shape or form have more pronounced effect on your overal engineering approach than adding a human remote dev to your implementation team, and your requirements engineering processes should really never notice the difference or need any serious adjustments.</p><p>And if you follow layered requirements principles, they won’t, and will be “right-sized” as a bonus.</p><p>Sure the level of details might vary (decrease), the iterations might be much quicker and just-in-time discovery might happen over mere minutes or hours rather than days and weeks, but all the principles will remain just the same and since the key role of requirements in any software project is to be the source for a shared mental model — as long as there are entities that needs to share the model, requirements are not going anywheree.</p><h3>Requirements maintenance post-development</h3><p>It’s time to address this quite significant elephant in the room; all this we’ve discussed so far (hopefully) makes sense for discovery, design, and implementation phases of the project, but the million-dollar question is “what happens to all those requirements after we deliver?”</p><p>If approached naively, the requirements quickly drift from the actual system implementation as many small changes, bug fixes, etc., are added to the system post-delivery, and implementation details change over time. The only way to prevent this (in this naive approach) is to more or less manually maintain BOTH the code and the requirements separately, and that, unfortunately, although it sounds feasible in theory, in practice, it just is not.</p><p>That said, there is one part of the requirements that does NOT change often or quickly — and is by lucky coincidence also the most compact one. I’m talking about a functional model. Think about it — the system was built to serve a functional purpose — that functional purpose does not change quickly over time. What does change over time is implementation details, an acceptance criteria is added here and there, UI gets changed a bit, or UX does — but the <strong>parts of the functional model</strong> they refer to <strong>remain largely the same</strong>.</p><p>What that allows us to do — and that is the approach the layered requirements are extremely suitable for — is to basically</p><blockquote>“torch” all the implementation requirements on project delivery.</blockquote><p>And when I say “torch,” I DO mean to completely get rid of:</p><ol><li>scope lists</li><li>assumptions list</li><li>Implementation layer</li><li>Acceptance criteria</li></ol><p>Basically, you just leave the functional model, NFRs, actors with vignettes, and the project summary. That’s it. That part remains the same, everything else will change quickly over time (details layer and acceptance criteria) or was relevant only during the implementation phase (scope, assumptions, etc)</p><p>What is left over is fairly small in size and low in detail (and therefore easily maintainable) — while still modelling the entire system and enabling any stakeholder to quickly build a mental model of the system at any point in the future.</p><p>With that said, I want to point out that any stakeholder can retain any part of the requirements they feel they need — this is fine, it is just outside this maintenance framework and therefore strictly speaking is not 100% necessary — but it’s not prohibited either.</p><p>However, there is one huge prerequisite before you can do any of that — and become free from needless requirements maintenance while still retaining the easily accessible functional model as a single source of truth when it comes to the system’s purpose and functional scope.</p><blockquote>That prerequisite is good, comprehensive, and AUTOMATED functional test suite and a corresponding CI pipeline.</blockquote><p>On top of that, your tests cannot be a tangled mess that only focuses on coverage, but rather they must be written and structured so that they are readable to non-coders (but also not completely a-technical) stakeholders.</p><p>That means writing proper functional “describe” and “it” statements in your tests — if you use the Jest testing framework, for example, or using Gherkin statements with ATDD tools, etc.</p><p>This is critical, don’t gloss over this — without that, the discoverability of implementation details for particular parts of the functional model becomes almost impossible or at least seriously impeded.</p><p>The logic behind ditching the written detail layer and replacing it with a functional test suite is that the implemented system’s details are fully and authoritatively defined by the <strong>implementation itself</strong>, and automated tests define/describe that particular implementation and its details. On top of it all, automated tests are (provided you have CI) “auto-verifying” in the sense that:</p><ol><li>If the underlying behaviour changes and is no longer in tune with the behaviours the automated tests “fix”, your CI pipeline will fail — and will keep failing until you rectify this discrepancy</li><li>If your system grows without tests following that growth, your coverage will go down, which is admittedly a lot fuzzier signal than failing CI, but still a very obvious and actionable one nonetheless</li></ol><p>None of this is a new concept; it’s called <strong>living documentation</strong> or <strong>executable specification</strong>, and we have known about it for decades now (also, we have known about the crucial importance of automated testing for roughly the same amount of time).</p><p>What usually prevented us from practising these obviously sensible and logical practices was the cost of writing comprehensive, usable test suites, which, for most teams, was prohibitively high (see the fallacy of expecting a mature self-organizing team in the previous chapter).</p><p>The good news is that that is no longer the case due to the advent of agentic and AI-assisted engineering (<strong>provided it is done as expert-driven <em>engineering</em> and NOT as vibe coding</strong>). Therefore, this practice is finally available to anyone who wishes to use it, and it gels perfectly with the layered requirements approach and its concept of functional model. Or at least that is true in my personal experience.</p><p>So to sum it up, the functional model + NFRs (you can have automated tests for those as well, btw. but that is besides the point) represent a compact, easy to consume “mental model builder” that changes little over time and can be consumed by any stakeholder in the future when needed. A built mental model provides grounding and the context for all the implementation details that are defined within automated tests, and that is crucial if you need to use or evaluate those details later in a proper context and not as isolated islands.</p><h3>Why does having internal standards help?</h3><p>Having internal standards is the most surefire way to prevent “but no one told me that I needed to write a test for it” discussions mid-development.</p><p>Regardless, in a lot of organizations, standards are often considered as something “extra”, something to have as a sign of maturity, but at the same time, often not really understanding how to properly use them, except through a “decree” and education.</p><p>And that is the shame, because in their core, internal standards and their usage are really simple and down-to-earth concepts rather than something complex that only “big boys/girls” need or know how to use.</p><p>When you think about them…</p><blockquote>internal standards are nothing more than a pre-defined set of NFRs that apply for particular domain</blockquote><p>For example, you might have code quality standards, SEO standards, test standards, usability standards, etc., but all of them are just requirements that apply to a project/deliverable as a whole.</p><p>Put another way,</p><blockquote>they are just acceptance criteria that need to be satisfied for some artifact to be considered “compliant”. Nothing more, nothing less.</blockquote><p>And that is (or at least) should be good news as acceptance criteria, their writing and their usage should be something well within our comfort zone by now, so standards really do not introduce any new complexity or special “usage instructions.”</p><p>So my advice to you is to figure out what do you want to be true for every artifact that gets delivered by implementation team, write in a form of list of acceptance criteria, make those explicitly linked to every PBI (or just create a NFR that project fully conforms to standard X, Y or Z) and you are golden (and if you use requirements forge tool, all that linking and inclusion in PBIs will be done for you by the tool :) ) and there you are — you have internal standards and what’s more imporant, you know what to do with them so they aren’t just dead letters on paper/screen.</p><h3>Applicable tools</h3><p>As mentioned above, layered requirements engineering is a non-opinionated framework when it comes to anything outside the internal structure of the requirements. That means that the choice of tools you’ll use to produce your requirements documentation is left completely to you.</p><p>For example, everything presented so far works perfectly fine with Jira, Azure DevOps, Trello, or just plain old Google Docs or MS Word.</p><p>The only feature of those tools that is really mandatory is good review and collaboration features. Those should include threaded commenting and the ability to assign threads to particular individuals and to explicitly resolve each opened thread with a proper audit trail. That is crucial for the review process, which is the topic that is both incredibly important and that also falls outside the scope of this particular article series.</p><p>So, although any tool conforming to the requirement above will work, here is an example of tools I typically use:</p><ul><li>When I write SRS documents or manifests, I use Google Docs and apply the continuous collaborative review approach whenever I can</li><li>When I create backlogs, I use whatever tool my clients use for that purpose — usually it is Jira, Trello, or some other tool that does essentially the same thing.</li></ul><p>For diagrams, especially those that will evolve during the project development, I use the diagram-as-code tool MermaidJS and integrate the resulting diagrams into the relevant requirements level as part of the detail layer.</p><p>If your team uses “physical” tools such as whiteboards, index cards, story maps, etc., you can continue using them without any modification. This framework is about producing the right content, not the tools you will use to document that content.</p><p>Some tools are better or more comfortable to use than others, but I’ve yet to encounter one that is so limited that it prevents applying this framework. As long as the tool has decent collaboration features, it will work well enough for our purposes.</p><h4>Requirements forge</h4><p>Although the framework itself is agnostic when it comes to tools, there were two main features that I missed from the tools I’ve just mentioned, and although those features were not by any means deal-breakers, and I’ve written many a good layered requirements document with Google Docs only, I still felt the itch that no tool I could find was able to scratch.</p><p>So I built one myself (or better said, I AM building one right now — it’s fully operational and I use it personally, but it is in public MVP phase, so if you’d like to try it out and give me feedback that will help me to make it better, you can <a href="https://reqforge.stabljika.hr/">check it out here</a>)</p><p>The missing features I was referring to, and which this new tool, called (Layered) ”Requirements forge”, implements are:</p><ol><li>fully hierarchical backlog management</li><li>auto-maintenance of referential integrity between every requirement element</li></ol><p>In its essence, this is a tool for writing requirements following the layered requirements framework and managing those requirements over the project’s lifecycle — as a functionally complete, semantically consistent structure — rather than just a flat backlog of freeform PBIs or a large freeform textual document.</p><p>I won’t go into further details, as that will be a subject for another article, but I’d like to point out one important benefit that I think structured requirements model allows for — and which is relevant in the age of agentic or AI-assited engineering we’ve touched upon in previous chapters, and that is the ability to transform this core semantic structure into pretty much any format you need — be it just a large freeform docx for organizations that don’t tolerate anything except word documents, or (much more relevant) an complete input for implementation AI agent — with definition of done, clear testing criteria, testable functional requirements and all relevant NFRs etc.</p><p>So that’s it about this tool, once again, if you want to<a href="https://reqforge.stabljika.hr/"> check it out, I’d appreciate any feedback</a> you might give me</p><h3>Conclusion</h3><p>There you have it. We’ve come full circle. We started with a disaster scenario, which is uncomfortably familiar to all of us who have ever participated in non-trivial software projects, and throughout this series, we addressed every major failure point of that scenario — even if not explicitly.</p><p>The inability to MVP and lacklustre demos were addressed by impact-driven progressive delivery in part 1 of the series. We also revisited it in this one when we discussed how end-to-end does not really imply that ends remain fixed throughout the project. That is a powerful concept when you think of it — the only important part is that there is someone who can achieve something that they couldn’t before. Everything else is strictly speaking an icing on that functional “cake”.</p><p>The continuous mid-project “surprises” were addressed by explaining the role of the requirements in the software projects and how to structure them in parts 2 and 3. In particular, the shared mental model — the most powerful remedy for “but I thought that…” situations and also the most ignored aspect of requirements usage IMO.</p><p>Finally, the ability to properly “spike” and prototype during the project was addressed in this article and in part 1, when we discussed progressive delivery and clarity of insights into what is tricky on the technical level it can allow for. The thing is that prototypes, without a clear connection to the functional model and therefore without a functional purpose, ie, what the given experiments/prototype will demonstrate and which risk it will mitigate, will not be “comprehensible” to non-tech stakeholders and, to their ears, end up sounding like an abstract developer’s playtime rather than a crucial risk mitigation tool.</p><p>However, framing it in the context of relevant functional impact fixes that misunderstanding beautifully. The communication and framing are key here, and functional model and progressive end-to-end delivery are what make the framing and communication obvious and understandable to the people that “hold the wallet”.</p><p>Also, we addressed a few points that we left out of our disaster scenario (for reasons of brevity) — such as that dreaded post-delivery documentation maintenance that seems to always be in the “we’ll cross that bridge when we get there” category, and showed that the bridge is actually very obvious and the stream very shallow and was never really intimidating at all. Also, we’ve hopefully shattered that aura of “that’s not for us, we’re not Google” about having organizational internal standards. It is simple, you need them, they are not complicated, and so they ARE for you, regardless of how small you think you are. They help a lot, don’t resist them just because the word “standard” makes you think about ISO and all the (non-existent) fun that moniker brings with it.</p><p>To sum it up. Software projects do not have to be unpleasant experiences.</p><p>Sure, there will always be elements out of our control that can mess things up, but on a run-of-the-mill software project, those are surprisingly rare and often quite foreseeable and therefore preventable.</p><p>Now that you have tools and know-how, the level of comfort that you will experience on your next project is really up to you — now that you know how, it’s time to just put it all in practice and enjoy the ride.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=bef2ec0fa10b" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Impact-focused software engineering part 3: layered requirements - details layer and tying it all]]></title>
            <link>https://medium.com/@vedran.krizek/impact-focused-software-engineering-part-3-layered-requirements-details-layer-and-tying-it-all-7329238e1ac0?source=rss-7049746239c7------2</link>
            <guid isPermaLink="false">https://medium.com/p/7329238e1ac0</guid>
            <category><![CDATA[software-development]]></category>
            <category><![CDATA[software-engineering]]></category>
            <category><![CDATA[agile]]></category>
            <category><![CDATA[requirements-engineering]]></category>
            <category><![CDATA[product-management]]></category>
            <dc:creator><![CDATA[Vedran "Brko" Krizek]]></dc:creator>
            <pubDate>Mon, 23 Feb 2026 07:46:00 GMT</pubDate>
            <atom:updated>2026-02-23T13:07:59.858Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*MYwFWH4PSrj7z4qwKKv-uA.jpeg" /></figure><h3>Impact-focused software engineering part 3: layered requirements - details layer and tying it all together</h3><h4>In the <a href="https://medium.com/@vedran.krizek/impact-driven-software-engineering-part-2-introduction-to-layered-requirements-and-the-project-fdfa73b07ac1">previous article</a>, we outlined the layered approach to requirements engineering, elaborated on its core components (layers) and ideas, and explained the functional model as part of the model layer. In this article, we’re picking up the story starting with the remaining part of the model layer — context model, and moving on to the details layer. Finally, we’ll talk about the part where the true magic happens and where it all hopefully comes together, the connection between the detail and the model layers.</h4><h3>The model layer: The context</h3><p>With the functional part of our model, we wanted to capture a high-level picture of what the system under design does, and for whom it does it. With the context part of our model, however, we want to capture the high-level picture of the environment in which the project itself will happen.</p><p>That includes answering such questions as “Why are we building this?”, “What is the complete — not just functional — scope of our project?”, “What are the constraints we’ll need to work with?”, “What are the assumptions that we’re making about the scope and environment?”, “Are there some global, non-functional requirements?”, and similar.</p><p>Although it might seem a bit redundant and superfluous at first, the inclusion of the context in the model we’ll be working with is often the difference between a well-managed, relatively “smooth” project and the endlessly falling row of “<em>we don’t call these problems, we call them challenges</em>” dominoes.</p><p>The reason that happens is because</p><blockquote>most projects do not fail or struggle because the implementation team is poor at their job</blockquote><p>but rather because managing software projects is intrinsically hard, and the impact of any issues in that domain has an exponential, disproportionate effect on quality and the implementation team&#39;s ability to deliver.</p><p>Said issues typically include</p><ul><li>wrong or incomplete project scoping,</li><li>unrealistic estimates,</li><li>poor implementation requirements</li><li>no shared understanding of the project model between different project groups, etc.</li></ul><p>This phenomenon is expertly elaborated in the essential “canonical” book “<a href="https://www.libristo.hr/hr/knjiga/mythical-man-month_04036858">Mythical man-month</a>” so I won’t go into more depth here but will rather encourage you to <a href="https://www.libristo.hr/hr/knjiga/mythical-man-month_04036858">read it</a>. It is a classic for a reason.</p><p>Another way of framing this is to say that the purpose of the context part of the project model is to provide a strong supporting framework for project management, just like the functional part of the model is there to provide the same type of framework for the implementation and delivery.</p><p>Having such a framework does make all the difference and is the reason why, for our purposes, the model of the project is much more useful than the model of “just” the system that is being built and delivered.</p><p>Now that we have dealt with the theory, let’s dive into the context part of the model.</p><p>Context can contain more segments than listed here, but I’ve found that the combination of</p><ol><li>summary,</li><li>the in-out-of-scope list</li><li>the assumptions list</li></ol><p>is, in my experience, the minimum that worked for any project that I’ve been involved with.</p><p>Additionally, I often add NFRs and glossary to the context part of the project model, but that is about it — I cannot recollect a situation where I used anything else.</p><h4>The summary/abstract</h4><p>Even with a good, complete, and easily “consumable” list of actors and their goals, we still want to make the life of our readers as easy as possible and provide as gentle an introduction into our project as we possibly can.</p><p>For that, we’ll use the same technique as scientific papers do — the abstract or a summary. Since the main content of a scientific paper is typically vastly more complicated than the typical requirements for a software project are, the reasoning here is that what works there will work even better for our simpler case.</p><p>Summary should be the first chapter in any requirements document, and should:</p><ul><li>Be written in prose form,</li><li>Be concise — typically not more than half a page long and</li><li>Summarize the project’s functional scope at an extremely high level</li><li>Address high-level reasons why the project needs to “happen,” such as listing main issues that exist and how the project would address them when finished</li><li>Give a broader context for the project (ie, “it’s a refactor of a legacy system”, etc.) and mention/list any organizational/regulatory, etc., obstacles.</li></ul><p>In short, after reading this short, easily accessible “essay,” the reader <strong>who was not previously familiar with the project </strong>should be able to understand what the project is about, why it makes sense, and in which context it will be built/implemented, and to understand it well enough that they could in theory “defend” the project’s reason-for-existing to a non-friendly third party.</p><p>The keywords for the summary/abstract should be “easily accessible” and “high-level”, so no deep details here; this should be the place you’ll apply those formidable KISS skills you possess.</p><p>Here is an example of a real-world summary:</p><p><em>Marin owns a small carpentry workshop and is required by law to keep track of his stock of materials and tools. There are numerous bookkeeping software solutions available, but they are pricey and full of features he doesn’t need.</em></p><p><em>What he needs is a stock management system with a “bare minimum” of features, which is also easy to use. He also doesn’t want to have to install the system locally in his office, but rather to be able to access it from anywhere where he has an internet connection.</em></p><p><em>The goal of this project is therefore to produce one such “minimal” online stock management system.</em></p><h4>The in-out scope list</h4><p>The “We thought this was also included…” is an opening sentence of many awkward and unpleasant conversations.</p><p>The easiest (and very effective) remedy is to just explicitly list what falls within the project’s scope and what does not. However, while doing so, we must always keep in mind that the project scope is not the same thing as the system’s functional scope; it does include it, but it is a wider concept that includes any action that will be taken as a part of the engineering and delivery process. It also should include any additional artifacts besides the system itself and any actions that will be taken post-delivery (ie, maintenance, etc.).</p><p>Here is an example of one such list:</p><p><strong>In scope:</strong></p><ol><li>Development of a stock management web application/system which implements the features defined in chapters X through Z of this document</li><li>Client support during the testing and acceptance phase of the project (including dumping or migration of test database, etc.)</li><li>Design of the hardware and hosting requirements for the clients devops/hosting team</li><li>…</li></ol><p><strong>Out of scope:</strong></p><ol><li>UI/UX design of all of the application’s user-facing interfaces</li><li>Any advanced reporting features</li><li>Any integration with third-party systems (such as bookkeeping applications, etc.)</li><li>Any formal security testing beyond validating compliance with the requirements of level 2 of the OWASP software maturity model</li><li>On-Production deployments (see assumptions)</li><li>…</li></ol><p>Hint: focus primarily on the out-of-scope list, as this is what will keep those unpleasant conversations at bay in most situations.</p><p>Scope lists work because</p><ul><li>they are easy to parse quickly by the business management (and clients too), and</li><li>they address the topics that are relevant and important to those stakeholder groups.</li></ul><p>As a consequence, reviews are typically quick, meaningful, and reliable, and any misunderstandings about the scope can promptly be discussed, cleared up, and the list updated to reflect the newly agreed-upon scope boundaries.</p><p>Having this list as a prominent, first-class element of your model effectively prevents those unpleasant conversations we mentioned at the beginning of this chapter.</p><h4>The list of assumptions</h4><p>It is said that assumptions are the mother of all f**kups and also that they make an ass out of you and me — and that is true if we’re talking about unspoken/silent assumptions. Those can and will break your project quickly and efficiently if they are allowed to “sneak in” unnoticed.</p><p>The best remedy here is obviously to make sure that no important assumption that unavoidably will be made during the project’s conceptualization remains unspoken.</p><p>Instead, we want to make doubly sure that any assumption is explicitly documented and treated as an integral and equally important element of the project model, as a scope list or a functional model.</p><p>The method for writing meaningful assumption lists is fairly simple and goes like this:</p><ol><li>First, think about all the reasons you can think of that prevent you from feeling secure in committing at this point (the stuff that scares/worries you — this is where your experience really kicks in)</li><li>Now visualize the reality in which those reasons do not exist, and in particular, pay close attention to what exists in their place — ie, with what you’ve replaced them within this new reality of yours</li><li>Write a “diff” between those two realities in as much detail as you can</li><li>Discover that the “diff” you came up with is, in fact, the list of assumptions that need to be fulfilled for the risks to go away.</li></ol><p>It is as simple as that, but here are a couple of important concepts to keep in mind while creating those assumptions:</p><ul><li>The list of assumptions is an explicit list of statements that all need to be true for this project to feasibly deliver its planned scope within the planned budget.</li><li>Make your assumptions AS PRECISE (“brittle”) as possible</li><li>Assume standard solutions whenever possible</li><li>Assumptions can only be the things that are not under your direct control. If it’s under your direct control and it has an impact on the project, then it’s your obligation/promise and not an assumption.</li><li>Assumptions in this context are always related to the project environment (what resources are already present, what state they are in, when will currently unavailable resources become available, etc.) — if an assumption deals with functional scope, then it should be a requirement or part of the scope list.</li></ul><p>And now let’s illustrate this with an example of one such assumption list:</p><ol><li>UI/UX design will be done by a third party and will conform to the functional requirements defined within this document</li><li>Completed UI/UX design will be available at least one week before the project starts</li><li>Accounting software used by the client’s official accountant can work with csv files containing the exported warehouse state and history data, without the need for any other data integrations besides said csv files</li><li>An IT operations provider’s staff has extensive experience and expertise in technologies Q, W, E, and at least 3 years of experience with each</li><li>The pre-existing provisioning API is RESTful, it is well-documented, and the documentation includes usage examples</li><li>…</li></ol><p>Don’t gloss over the assumptions and assume (see what I did there?) that they are not so important in your case — they are, I have had my proverbial behind literally saved by just a few well-documented assumptions on more than one real-world occasion.</p><p>Also, since the mistakes do happen, and they happen on both sides of the project “equation,” having explicitly documented assumptions as a first-class artifact of our project model greatly helps with keeping the conversations that will take place when things do “go south” constructive and fruitful.</p><p>I’ve written an entire article on the techniques of using assumptions as a tool for managing project entropy. So if you want to know more about the whole concept, you can <a href="https://medium.com/@vedran.krizek/the-power-of-the-assumption-the-introduction-97c4e36ca2b">check it out here</a></p><h4>The glossary (ubiquitous language)</h4><p>This one is not mandatory, but I’m still including it here because I think it is a good idea to have it, as it helps with alignment between stakeholder groups. The term and the concept come from DDD (ubiquitous language), and it is just a dictionary of terms that are either non-standard in general or might not be part of a common dictionary for one or more of the stakeholder groups that will read the requirements doc.</p><p>The only real point to keep in mind here is that for each term listed, the explanation must be understandable to ALL stakeholder groups relevant to the project — not just a few that have necessary pre-existing knowledge (technical, for example).</p><h3>The details layer</h3><p>One of the most appealing aspects of the layered approach is that it does not require you to change the way you document details.</p><p>What this means in practice is that this will be a very short chapter, and that is not by accident or because I’m lazy (I am, but that is not the factor here).</p><p>Its brevity should illustrate one important aspect of the requirements engineering approach presented on these pages.</p><blockquote>You, the business analyst or the requirements engineer, already know all the building blocks and formats for writing detailed requirements; you know how to use them and have been using them throughout your career.</blockquote><p>Therefore, you don’t really need someone like me to come along and teach you some new format and tell you that what you learned so far sucks and should be thrown away and replaced with “new method (™)” which has some magical properties that will fix all that is wrong with your BA/PO/RE life.</p><p>It won&#39;t, because</p><blockquote>Whatever IS wrong in your BA/PO/RE life, I’m willing to bet it is not due to you not knowing how to write a well-structured use case or define a data model or a business rule.</blockquote><p>So, the approach outlined in these articles is about using what you <strong>already know,</strong> but in a way that produces results drastically different from the ones you’re used to.</p><p>Therefore, for scenarios, UX interactions, and any other important detail that can be modeled with a sequence of steps, you’ll keep using use cases, either in textual or graphical/diagram form.</p><p>Likewise, for business rules, you’ll still use something like specification-by-example or some other applicable format that “sits well” with you.</p><p>For data model/entities, you’ll keep using one of many formal formats designed especially for that purpose, and you’ll still use Figma or some similar tool for UI wireframes and “clickable prototypes”, and so on.</p><p>The point is — for the details, any formal formats will work — there is no right or wrong here, provided you <strong>USE THE CHOSEN FORMAT CORRECTLY</strong> and for its intended purpose.</p><p>And I’ll stop here because</p><ol><li>There are numerous foundational books written on individual formats (for use cases, there is no better than “Writing effective use cases” by Alistair Cockburn, for business rules, there is an excellent “Specification by Example” by Gojko Adzic, etc.) — go and read those if you feel you need to polish your detail documenting game</li><li><strong>The important part is not how the details are documented but rather how they are connected to the project model </strong>— and that is what we’ll discuss in the next chapter</li></ol><h3>Linking layers</h3><p>This is where the magic happens.</p><p>To make all we’ve covered so far work together as a cohesive system, we need</p><blockquote>An unambiguous and explicit way to connect the functional part of our project model, defined via a hierarchical actor-goal list, and all the important details defined using various formal formats.</blockquote><p>In other words, we need to link the model and detail layers in a way that is direct, easily readable, and unambiguous</p><p>Luckily for us, there is one (often misunderstood and misused) format that is perfect for this, and is even named accordingly.</p><p><strong>The acceptance criteria.</strong></p><p>Think about it — we have a goal statement (actor-goal) and an open question asking the following:</p><p><strong>“What specifically needs to be true — BESIDES THE OBVIOUS FACT THAT THE GOAL CAN BE DEMONSTRATED TO BE ACHIEVABLE — to consider this done?”</strong></p><p>Or put another way,</p><p><strong>“What are the DETAILS I CARE ABOUT on how the actor is achieving this goal?”</strong></p><p>The concept of acceptance criteria is exactly what was invented to answer those questions.</p><p>And when I say acceptance criteria, I do not have any complicated formats in mind — as ANY acceptance criteria is simply:</p><p><strong>A declarative, present-tense statement that can UNAMBIGUOUSLY and EASILY be demonstrated to be either true or false.</strong></p><p>Another way of putting it is:</p><p><strong>An acceptance criterion is a statement that can be easily demonstrated to be FALSE before the item of work it relates to was finished and is demonstrably TRUE afterwards.</strong></p><p>It is that simple. However, since examples speak volumes, here are a few actual examples of acceptance criteria linking actor goals with particular details defined elsewhere (all references in the example, like UC-1.2, UIT-14.3, are just illustrations):</p><p>Goal:</p><p>A warehouse manager can see the details of any individual contract</p><p>Acceptance criteria:</p><ol><li>When the list of invoices is rendered within the administration UI, then the user is provided with the means for asking the system to display any of the listed invoices</li><li>When the user asks the system to display the invoice, then the UX is conformant to use case UC-1.2 AND UX/UI template UIT-14.3</li><li>The rendered invoice contains all data elements defined in DM-11.2 marked as “Readable by authorized users.”</li><li>…</li></ol><p>Assume that elsewhere in the document, we have</p><ol><li>a formal use case describing the user-system interaction for rendering invoice details, and it’s labeled UC-1.2 (you can label them however you like, I use format name shorthand + numerical identifier, but that is really nothing more than my preference)</li><li>A data model for the invoice labeled DM-11.2</li><li>UI template/wireframe labeled UI-14.3</li></ol><p>What we achieved is this:</p><ul><li>We have defined all details within its own layer and nowhere else — fully honoring the DRY principle and consequently contained all the reading complexity within a well-defined single layer (separation of concerns)</li><li>We made each element of the detail layer referable by giving it a unique ID (slug)</li><li>We have directly and explicitly linked individual details from the detail layer to individual goal statements (or entire functional model in case of NFRs) using acceptance criteria and referencing detail IDs</li></ul><p>I won’t delve further into acceptance criteria themselves, as I have <a href="https://medium.com/@vedran.krizek/acceptance-criteria-demystified-48a817c2f9ca">written extensively about them here</a>. However, I will highlight one crucial aspect of how they should be written and used during the project implementation phase.</p><p>The art of writing “approachable” requirements is in what you leave out of them, while not jeopardizing their usefulness and the role they need to serve on a project. The place where this is most obvious is writing acceptance criteria.</p><p>For example, you might be tempted to define every single detail of the implementation by writing a bunch of acceptance criteria for a particular goal statement, covering all details of its expected deliverable but that will result in:</p><ul><li>hard to read, dense requirements (a long list of accs is as unreadable to a layman as the complex use case is)</li><li>micromanagement of the implementation and the forfeit of leveraging the pre-existing internal standards, professionalism, and expertise that the implementation team can bring to the table</li></ul><p>What you want to do instead is define only those CRUCIAL details in an IMPLEMENTATION AGNOSTIC way (ie, “The system informs the user when the operation fails and provides them with needed information to start troubleshooting the problem” rather than “The system slides the red information box from the bottom of the screen with the text xyz…” etc.) and then</p><blockquote>You let the implementation team fill ALL THE REMAINING GAPS with their common sense, expertise, and organization standard solutions.</blockquote><p>This way, you end up with</p><ul><li>easy to read requirements (5–7 accs per story is easily “parsable” by anyone)</li><li>full utilization of your team’s expertise</li></ul><p>Put another way, acceptance criteria (along with the goal statement) form a key part of a “contract” between the product owner/BA/PM and the implementation team, and that contract goes something like this:</p><p><em>As a product owner (or BA or PM), I expect that any unit of work delivered to me will have its related actor-goal demonstrably achievable. Besides that, the only thing I will ever hold you accountable for is the fulfillment of the relevant acceptance criteria. If there is a behavior that I don’t like — and it’s not in violation of any of the existing acceptance criteria for that unit of work — even if it is obviously wrong, that is still “on me”, and I will create an additional unit of work that will have the appropriate acceptance criteria to address it. Additionally, I will NOT reject the delivered unit of work on that basis and will still treat the iteration goal as achieved regardless.</em></p><p>This allows the implementation team to FREELY provide any “non-critical” details (ie, whatever is NOT explicitly listed in acceptance criteria) while fully leveraging their expertise and organization’s technical quality standards. At the same time, all the important details BA/PO explicitly cares about are made invariant and protected by explicit acceptance criteria.</p><p>Another way of stating the above is to say that :</p><blockquote>The goal statement and its acceptance criteria are immutable constants; everything else is variable.</blockquote><p>That is the only way that I know of that allows you to have your cake (invariants) and eat it too (have the implementation team provide added value through their expertise on everything else).</p><h4>Non-functional requirements</h4><p>There is no real difference in how we handle non-functional requirements compared to any other element of the detail or model layers. Non-functional requirements are still requirements, or conditions that need to be met for the project to be compliant with our expectations for it, so everything said so far about functional requirements applies, without modification, to non-functional ones as well.</p><p>The main difference between a typical functional and non-functional requirement is that functional ones are directly connected to a particular goal statement(s), while non-functional ones are connected to the entire model.</p><p>For example, if we have a performance requirement like:</p><p><em>Every page from the list of pages BR-2-PERFORMANCE-PAGES has its TTFB under 100 ms on an internet connection compliant with the minimal connectivity requirements stated in BR-2-CONNECTIVITY.</em></p><p>That one is clearly an acceptance criterion — the only difference being that it does not relate to a particular part of the functional scope but rather to its entirety.</p><p>One way I prefer to document non-functional requirements is to have a separate chapter listing the “global” acceptance criteria, with the parent/owner set to the entire project scope. I tend to put this section in the context part of the model layer, since it addresses the project as a whole. As usual, YMMV.</p><h3>Summary</h3><p>There you have it, this article completes the main story about layered requirements.</p><p>To me, the main strength of this framework is that it does not force or even encourage you to throw away your hard-earned knowledge about formal documentation formats and replace it with something novel and cool(TM), but rather allows you to put what you already have to good use — in the context of crucial roles requirements serve which we <a href="https://medium.com/@vedran.krizek/impact-driven-software-engineering-part-2-introduction-to-layered-requirements-and-the-project-fdfa73b07ac1">discussed in detail in the previous article</a>.</p><p>In other words, you were almost “there” this whole time, and what I’ve presented here merely helps you make that final step, one that apparently makes all the difference.</p><p>For me, this framework also finally made acceptance criteria, and their place in the overall software engineering process, make sense and helped me understand why they aren’t “just another requirements format” but something rather different and incredibly useful.</p><p>However, the story doesn’t fully end here; we still have some loose ends and obvious questions left unanswered. Questions such as “well this is all nice and good, but we’re doing agile here and have no need for big requirements documents, does layered requirements make sense in agile scenarios? and if so, how exactly?”, “What about requirements maintenance AFTER the engineering is completed?”, “We live in the age of AI-assisted software engineering and agentic AI coding, how does all this apply in these scenarios?” and finally “what tools can we use?”.</p><p>We’ll answer all those (and a couple more) in the fourth and final article in this series, and the answer to the last question I’ve listed above will have a little surprise included, so stay tuned.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=7329238e1ac0" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Impact-driven software engineering, part 2: Introduction to layered requirements and the project…]]></title>
            <link>https://medium.com/@vedran.krizek/impact-driven-software-engineering-part-2-introduction-to-layered-requirements-and-the-project-fdfa73b07ac1?source=rss-7049746239c7------2</link>
            <guid isPermaLink="false">https://medium.com/p/fdfa73b07ac1</guid>
            <category><![CDATA[software-engineering]]></category>
            <category><![CDATA[requirements-engineering]]></category>
            <category><![CDATA[agile]]></category>
            <category><![CDATA[software-development]]></category>
            <category><![CDATA[product-management]]></category>
            <dc:creator><![CDATA[Vedran "Brko" Krizek]]></dc:creator>
            <pubDate>Mon, 02 Feb 2026 11:57:27 GMT</pubDate>
            <atom:updated>2026-02-26T12:01:45.585Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/960/1*XWy7CoBJQXwIXHX_LtMSeA.jpeg" /></figure><h3>Impact-driven software engineering, part 2: Introduction to layered requirements and the project model</h3><h4>Good requirements can make a project, but unfortunately, bad ones can break it. And no, the “communication over documentation” ideas from the agile manifesto do not provide an easy way out of this conundrum. In this article, we’ll discuss a framework for documenting requirements that meshes perfectly with the concepts of impact-driven software engineering and progressive impact delivery and does not force you, the writer, to change your preferred project methodology. The framework is called “layered requirements engineering,” and we’ll discuss its foundational concepts and begin explaining its first key element— the model layer.</h4><h3>Intro</h3><p>This one is about requirements.</p><p>In the <a href="https://medium.com/@vedran.krizek/impact-driven-software-engineering-part-1-the-impact-and-impact-focused-delivery-ccd2ecd67e6c">previous article</a>, we’ve defined what the functional impact is and how we can address many of the “classic” problems we encounter on our projects by taking a lesson from the past in the form of progressive JPEGs, an ancient image format ubiquitous at the dawn of the internet some 30+ years ago, when the bandwidths were quite constrained. As a result, in those days, you needed to get your message (impact) across as optimally and quickly as possible.</p><p>Replace the term “bandwidth” with “project budget,” and suddenly things stop being about images and start to look suspiciously similar to the value delivery in software projects.</p><p>We also mentioned something called “shared mental model” and what happens if it does not exist on your project, and (no spoilers here…) it’s not good.</p><p>And since we all know that whatever shared mental model is supposed to be, the role of requirements is to document everything important anyway. So… we should be fine there? or?</p><p>No.</p><p>Let me explain.</p><h3>The role of requirements</h3><p>Let’s clear one thing up right from the beginning.</p><blockquote>The role of the requirements documentation IS NOT to “document all the client wants or needs,” and it certainly is not to “document all the details for the developers” — or any variation of those.</blockquote><p>The role of the requirements documentation is twofold, and it goes like this:</p><p>The <strong>PRIMARY</strong> role of requirements documentation is</p><blockquote><strong>To model the project scope in sufficiently high level so that it does not imply implementation details, and to document it in a way that can be EASILY understood by EVERYONE, ie, any of the project stakeholders, regardless of their technical background.</strong></blockquote><p>That “<strong>easily understood by everyone</strong>” part is crucial if we want that model to be realistically shareable between project stakeholders. If that is not the case, the effective collaboration between those stakeholders will be seriously impeded.</p><p>So the primary role of the requirements is to ensure that the project model is designed, documented, and easily accessible by every stakeholder group.</p><p>However, just the model itself is not enough, as we can all agree that there ARE such things as important details.</p><p>For example, some details are crucial for UI designers, others are crucial for the development/engineering team, etc.</p><p>Also, we need those details documented for effort estimation, project planning, identifying implementation/technological risks, etc.</p><p>Therefore, we cannot omit details, and so the requirements documentation has a SECONDARY role as well.</p><p>And that role is:</p><blockquote><strong>to define IMPORTANT details in such a way that those details are documented using appropriate standard formats that are EASILY “consumable” by the INDIVIDUAL GROUPS to which those particular details are important</strong></blockquote><p>In other words, while the <strong>documented project model MUST be easily accessible to everyone</strong>, that is not the case for the <strong>details</strong>, as those <strong>need to be accessible only to individual groups that will be depending on them</strong>.</p><p>There is also one implied property naturally emerging from these two definitions, and those keen-eyed among you might have already figured it out — first of all, good work, and second, don’t worry, we’ll address it in the next chapter.</p><p>So now that we understand the dual role of the requirements documentation, we need to figure out how to build ours with those roles firmly in mind.</p><p>However, before we dive right into it, let’s first define one term that is both central to the presented argument and whose meaning is often misunderstood by both the business analysts and product owners.</p><p>I’m talking about the model.</p><h3>The model — system vs. project</h3><p>To make things as unambiguous as possible, as the term “model” can take multiple meanings depending on the context it is used in, we’ll define it as follows:</p><blockquote><strong>The model of something is a SIMPLIFIED version of it, where the simplification is designed so it preserves only those properties relevant for the purpose it will serve.</strong></blockquote><p>That means the best models are those that include the absolute minimum amount of properties needed for their purpose and not a single “extra” one.</p><p>Another way of putting it is to say that most good models are small — at least when compared to the real-world artefact or phenomenon they model.</p><p>Furthermore, we’ll state that:</p><blockquote><strong>Any model is purpose-built, ie, it is a simplification of a reality built to serve a PARTICULAR PURPOSE</strong></blockquote><p>ie, models are never ends in themselves, but rather a foundation/input for a subsequent design or analysis process.</p><p>In our case, the purpose/function that we need our model for is</p><ol><li>understanding the system’s function (what it does),</li><li>understanding the context and the environment in which it is being built (for example, why the system needs to be built and delivered, the project environment in which it will be built, etc.)</li></ol><p>So right from the bat, we need to make one very important distinction about “our” model, and that is that:</p><blockquote><strong>The model we’re documenting </strong>IS NOT<strong> the model of the system we’re building, but rather the model of the PROJECT we’re undertaking.</strong></blockquote><p>In my opinion, this is a crucial distinction, as software projects encompass both the end artifact (the software system) being delivered, as well as the context and the environment in which the process of building that artifact takes place.</p><p>And the reason this is important is that if we limit our model to just the system, we’ll lose the ability of various project stakeholder groups to effectively collaborate on anything EXCEPT the functional scope of that system. For example, if we go with just the model of the system, we’ll be omitting such important things as general project constraints, assumptions we inevitably made, delivery context, organizational challenges, etc.</p><p>It is a big “blind spot” to have on any non-trivial project, and I’ll even dare to say that if it is not the root, then it is at least the major contributor to most typical issues on your average project.</p><p>So, whenever you see the term “model” or a “documented model” in the remainder of this document, keep in mind that we’re talking about the <strong>model of the PROJECT</strong> as a whole, and not merely the model of the SYSTEM that is being built as a deliverable outcome of that project.</p><p>Therefore, the model we’ll be discussing in the upcoming chapters will be composed of the following two key elements.</p><ol><li>Functional model of the system— defining “WHAT the system allows its stakeholders to achieve“ in an implementation-agnostic way</li><li>The model of the Context/Environment in which the system itself will be built</li></ol><p>With that out of the way, we’re finally ready to dig into the layered approach to documenting requirements, which is a non-opinionated framework that takes into account all that we’ve discussed so far and produces a requirements document that serve their dual purpose effectively.</p><h3>Layered requirements</h3><p>We won’t be saying anything new or controversial if we state that any requirements document, regardless of its form, will have multiple groups of readers with very different expectations and needs for the document’s content.</p><p>However, if we ignore that fact and do not adjust our approach to structuring the content in our requirements documents accordingly, we’ll fail at least one of those groups and make their job much, much harder, and consequently impede the project as a whole.</p><p>Therefore, what logically follows is that the approach we need must be a multi-tiered (a.k.a. “layered”) one, where we have at least two tiers and where the first tier defines the model and all subsequent tiers define details of that model, and that those tiers will be aimed at different audiences and therefore should be structured and written differently from each other.</p><p>Another thing that logically follows, if the resulting requirements are to be consistent with themselves and useful as a whole, is that:</p><blockquote><strong>There must be a direct 1-to-1 link/connection between each of the individual “important details” and a particular “parent” element of the documented model</strong>, <strong>and that link must be both clear and unambiguous.</strong></blockquote><p>Without that, the second tier/layer (a.k.a. “detail layers”) becomes merely a disjointed archipelago of details, and as a result, there will be a fundamental detachment between what the implementation team envisions the project to be (details) and what the business/management thinks it should be (documented functional model).</p><p>This is a real problem because the difference in understanding of what is being built and the context in which it is being built is the key factor that prevents effective collaboration between individual project stakeholder groups and often breaks projects as a result.</p><p>So to recapitulate:</p><p>Layered requirements is a framework for documenting requirements that:</p><ol><li>Ensures that the high-level model (a.k.a. “scope”) of the system under design (including the context it will be built in) is documented in such a way that it is easily consumable by any project stakeholder group — including explicitly non-technical readers</li><li>Ensures that the aforementioned model is documented in a way that allows it to be formally validated to be complete and accurate (ie, “functionally complete” — we’ll cover what that means in the upcoming chapters)</li><li>Ensures that all important details about the model (business rules, use cases, data models, etc.) are documented in a way that is suitable for particular project stakeholder groups that will consume/need them</li><li>Ensures that there is a direct and unambiguous link between the model and the details</li></ol><p>Now you might ask the obvious question: “But we have many, many ways of writing requirements. What is wrong with them? Why do we need another one?”</p><p>There is nothing inherently wrong with any of them, but at the same time, none of them put any real emphasis on what we’ve discussed so far, so as a result, this is what usually happens with some of the standard approaches if used naively/without consideration of what we discussed so far.</p><p>SRS Documents usually end up suffering from the following:</p><ul><li>Heavy on details (important or not)</li><li>Light on functional scope (usually just an incomplete feature list)</li><li>Dense with formal formats (data models, use cases, business rules)</li><li>No clear connection between high-level scope and details</li></ul><p>As a result, they are often just developer documentation that the business can’t read. No shared mental model to be found there.</p><p>And Product Backlogs will often suffer from the following:</p><ul><li>No high-level project model</li><li>Hard to verify completeness as the scope is often fragmented</li><li>Goal statements are buried in flat lists (backlogs are typically flat)</li><li>Natural hierarchy lost (goals are hierarchical by nature)</li></ul><p>As a result, even well-written PBIs don’t create shared understanding without structure and supplemental materials — and both are usually missing.</p><p>And to be clear, none of the classic approaches to writing requirements prohibit or actively prevent you from doing it in a layered way, or go out of their way to discourage implementing multi tiered approach I’ve outlined so far.</p><p>In traditional setting that is usually assumed to be the responsibility of the writer — which is fine, but unfortunately, in practice, I’ve found that this is seldom addressed, and as a result, the usefulness of the requirements as whole is frequently diminished to the point at which they serve as a “overwhelming source of often confusing or contradictory information” — which is only marignally better than not having any at all.</p><p>So now that we understand our core concept, we are ready to dig into its first component, the model layer.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*5quW-rqoqfZgTI4u0Q1ytA.png" /><figcaption>Fig 1. Layered requirements architecture</figcaption></figure><h3>The Model layer: The structure</h3><p>Since we now know that our model describes the system and the context in which it will be built, our documented model will be structured to reflect that fact (don’t worry about the terms actors, goals, in-out scope lists, etc., we’ll explain those shortly):</p><h4>Functional scope</h4><ol><li>Actors</li><li>Goals</li></ol><h4>Project context</h4><ol><li>Summary</li><li>in-out of scope list</li><li>Assumptions</li><li>supplemental materials</li><li>Glossary</li><li>…</li></ol><p>Let’s start from the top.</p><h3>The model layer: Functional scope</h3><p>The functional part of the model answers the following question:</p><blockquote>“What should the system we’re going to build do for those who will interact with it in any way?”</blockquote><p>We’ll use this initial question to figure out what might qualify as a good format to document the functional scope with.</p><p>The key lies in this “<strong>WHAT</strong> it should do for <strong>THOSE</strong> who will interact with it” statement. Those keen-eyed amongst you might remember that this sounds suspiciously similar to the <strong>positive functional impact</strong> we described and defined in the <a href="https://medium.com/@vedran.krizek/impact-driven-software-engineering-part-1-the-impact-and-impact-focused-delivery-ccd2ecd67e6c">opening article</a> — and that is because that is exactly the case.</p><p><em>There is SOMEONE/SOMETHING that can NOW ACHIEVE SOMETHING (using the system under design) that they could not achieve before.</em></p><p>The lesson here is that</p><blockquote>Functional scope of a system is the sum of all positive functional impacts that system is going to have.</blockquote><p>So we have our two guides, WHATs (achieve something) and (for) WHOMs (someone/something).</p><p>And one important insight we need to have here is that when you combine WHAT and WHO in a declarative statement, what you get is a goal statement, also known as a user story.</p><p>That also means that:</p><blockquote>Positive functional impact, goal statements, and stories are essentially the same thing.</blockquote><h4>Why do goal statements/stories work?</h4><p>For example, here are a few goal statements/stories:</p><ul><li>Visitor (WHO) can register and become a registered user (WHAT)</li><li>Registered user (WHO) can log into the admin UI (WHAT)</li><li>Registered user (WHO) can browse their paid and pending invoices (WHAT)</li></ul><p>… we could go on, but you get the picture</p><p>The reason why that particular format is extremely suitable for our purpose is this:</p><ol><li>Stories and storytelling are the most effective way of communicating high-level/concept information between humans; this is an evolutionary fact well supported by multiple studies (*).</li><li>A corollary of the first point is that if we define the goal as a story, then multiple stakeholder groups will all be able to internalize and understand that story easily and then COLLABORATIVELY work out the “important details,” which is exactly what we need.</li></ol><p>As a result, stakeholders with radically different backgrounds, like for example CTO, CEO, project tech lead, project manager, product owner, UI designer, etc., can all sit around the “proverbial campfire”, tell a particular story, internalize it, and then contribute their unique perspectives and ideas in an informed and collaborative way.</p><p>That is something that is simply not realistic with feature lists, formal requirements like use cases, Gherkin ACCs, data models, or even diagrams, and UI wireframes.</p><p>One way to understand how it works is that we can think of a story as a vessel for information that is shaped in a particular way. Telling a story instantly transports (incepts) that vessel into the listener’s mind and allows them to fill said vessel with details and information on their own, adding their unique perspective and expertise.</p><p>In software engineering project that means that “Registred users can see the history of their purchases” will create the similary shaped “information vessel” in the minds of CTO, Head of marketing, UI designer, tech lead, product owner etc. and then, guided by the BA/PO, they will be able to provide meaningful details from each of their unique perspectives while still honoring the “shape” of the vessel (a.k.a. goal statement) — in a way that is natural and does not need to be learned as a technique.</p><p>What this also means is that a story/goal statement is something that is as understandable to the CEO of the company as it is to an intern developer and everyone in between. It is a universal language that spans the entire project domain and all of its stakeholders.</p><p>If the goal is, for example, <strong>“Registered user can see and browse the list of their paid invoices”</strong>, then it is obvious to everyone whether some implemented piece of the system allows for that goal to be achieved or not, without going into any details — just by trying to demonstrate it.</p><p>“They” say that the proof of the pudding is in eating — and “they” are right.</p><p>So now that we understand how the stories and goal statements work for our particular purpose, we’re ready to move on to the nitty-gritty parts, and we’ll begin with the “WHO” part of our goal statement.</p><p>(*) References: Smith, D., et al. (2017) — Cooperation and the evolution of hunter-gatherer storytelling. Green, M. C., &amp; Brock, T. C. (2000). The role of transportation in the persuasiveness of public narratives.</p><h4>WHO? Actors.</h4><p>We’ll call each “WHO” an “actor”. The terminology is borrowed (or rather stolen) from the domain of Use Cases and, in particular, from Alistair Cockburn’s excellent book “Writing Effective Use Cases”.</p><p>For our purpose :</p><blockquote>Actor is any entity that interacts with the system either directly or indirectly.</blockquote><p>Example of actors in a typical system might include: a customer, a data analyst, a warehouse manager, a head of accounting, an accountant, a system administrator, an external auditor, etc.</p><p>Now, just having a well thought out list of actors that will interact with our system is better than nothing, but we all know that in all good stories, characters are fleshed out much more than just by giving them names/roles, and so we’ll do the same, and for each of the actors, we’ll write a short character background-providing “vignette”.</p><blockquote>“Vignette” is a short description of each actor’s situation/context relevant for the project at hand</blockquote><p>Vignettes are typically written in prose form — although some like it structured as multiple bullet list items where each addresses some of the standard topics for a vignette. The structure is not really important — the content is king here, and here are some questions that a good vignette should try to answer:</p><ul><li>What does the actor do in their line of work?</li><li>What is their daily focus?</li><li>What are the main problems they encounter?</li><li>What is important for them and what is explicitly not?</li><li>What is their motivation?</li></ul><p>You might rightfully ask if this “vignette thing” is really necessary, as it looks a bit excessive at first glance, and the answer is “yes, it really is”.</p><p>The reason for it is that if we’re to use stories effectively as a “model describing/detail discovery” tool, we need to give those stories as much “flesh” or context as possible — and having real actors and understanding where they come from provides that context in a way that fully leverages how humans <strong>naturally</strong> process information.</p><p>Put simply, we all internalize a story with context much more easily and naturally than a generic one.</p><p>So now that we know this, here is an example of a real-world vignette:</p><p><strong><em>Warehouse Manager — Maria</em></strong></p><p><em>Maria manages inventory for a small manufacturing shop. She’s responsible for tracking 500+ items across 3 warehouses and ensuring production never stops due to missing materials.</em></p><p><em>Currently, she uses Excel spreadsheets that break when multiple people edit them simultaneously. She spends 2 hours each morning reconciling inventory counts from different sources.</em></p><p><em>Maria needs a simple but reliable system that lets her see real-time stock levels, track item movements, and get alerts before critical items run out. She’s not tech-savvy and needs something intuitive that “just works.”</em></p><p><em>She works both from the office and occasionally from the warehouse floor using a tablet.</em></p><p>Now, let me point out that you can define actors iteratively; no one expects you to identify them all in one fell swoop.</p><p>In the real world, you’ll start with obvious ones, and while you define the model further and further, you’ll naturally discover more hidden actors (and their goals), and so you’ll be expanding your actor (and goal) list iteratively. This is perfectly fine, and everyone I know does it the same way.</p><h4>WHAT? Goals.</h4><p>We already know we’ll use goal statements/stories for documenting the functional part of our model, but there is still some finesse when it comes to structuring those goal statements and addressing the individual “WHAT” parts, and we’ll explain that here.</p><p>Here are a couple more examples of the goal statements:</p><p><strong>A Warehouse manager (WHO) can browse and manage invoices (WHAT)</strong></p><ul><li><em>Warehouse manager (WHO) can find invoices by their unique number (WHAT)</em></li><li><em>Warehouse manager (WHO) can find invoices by their due date (WHAT)</em></li><li><em>…</em></li></ul><p><strong>An Administrator (WHO) can manage access accounts for the admin UI (WHAT)</strong></p><ul><li><em>Administrator (WHO) can create new admin UI access accounts (WHAT)</em></li><li><em>Administrator (WHO) can suspend any existing admin UI access account (WHAT)</em></li><li><em>…</em></li></ul><p>Note that in this example, the statements are ordered hierarchically, from higher-level goals to lower-level ones.</p><p>This matters because a hierarchical structure allows for</p><ol><li>Much easier readability and “parsing” of the functional model than it would be in a case of just a flat list</li><li>Granulated Multi-tiered approach to the model itself — for example CEO can read only those 7–10 highest-level goals and quickly understand whether the system will deliver the impact he/she expects from it, and ask informed, relevant questions or provide meaningful feedback, while the product owner or manager can go into sub-goals while working with the implementation team and discussing and discovering important details</li></ol><p>This really does make a difference, and I strongly suggest that you follow this structure as well.</p><p>Finally, I want to mention that although there are formal formats that you can use, such as the canonical user story format, etc., they are just scaffolding, and I encourage you not to make much of them, as it is very easy to focus on the format and lose track of the content you’re filling it with, resulting in something that looks fine from the outside but contentwise is completely broken and unusable. The term used by Jeff Patton in his brilliant book “User Story Mapping” for people who do that is “template zombies.” Don’t be one.</p><p>Now, about that nuanced “WHAT” part, and how to formulate it. It is fairly easy and comes to two simple rules that goal statements need to fulfill to be useful for our purpose:</p><ol><li>They must be easily demonstrable — and unambiguously so (<strong>this is critical</strong>, as we’ll see later in the text), and so</li><li>They must be objective and explicit — for example, no relative terms like “better”, “more”, etc. should be used when structuring them.</li></ol><p>In essence, the key criteria and the question you should ask about any of the goal statements you are writing is this one:</p><blockquote>“Would I be able to confidently demonstrate that this goal is achieved for this particular actor, to a room of sceptical audience?”</blockquote><p>If the answer is anything but a sound “yes,” your goal statement is not objective, explicit, or precise enough, and you need to address that immediately.</p><h4>Functional completeness — why it matters and how to verify it?</h4><p>If we want our model to be useful rather than misleading, it must be functionally complete and consistent with itself — meaning that the scope it defines has no functional holes (for example, there is a functionality for accessing X but there is no notion of how that X is introduced, etc.) and that every goal statement in a hierarchy of actor goal statements is directly supporting it’s parent goal.</p><p>This is important because, if you have the system that needs to achieve a particular set of high level goals, and you can verify that the functional model of the system fully facilitates and supports those goals and that there are no functional holes or inconsistencies within it — then you can be sure that the system makes <strong>functional sense</strong> and that the risk that you omitted some important feature is extremely low. That is because:</p><blockquote>A functionally complete system that results in all relevant high-level goals being achieved for corresponding actors can not, <strong>by definition, have any critical features missing</strong>, simply because whatever a feature is, it cannot be critical if even without it the key goals of the system can be achieved.</blockquote><p>That is a great safety net to have before you dive into the details, because you know that whatever the details you discover, design, and document will be detailing a system that is complete and achieves its purpose.</p><p>So, how to formally verify your functional scope? There are quite a few methods for doing that — some VERY formal and complicated, but I’ll mention two that I personally use — one is a simple but formal method for direct validation, and another is a discovery method that produces a set of goal statements/stories that are reasonably functionally complete from the start.</p><p><strong>Method 1: C.R.U.D. method</strong></p><p>This is a quite simple but nevertheless an effective method where you first identify all the nouns (a.k.a. “entities”) that your actor goal list implies (ie. “invoice”, “contract”, “stock item”, “invoice item”, “account”, etc.) and then for each of those go over your list of actor goals and verify that there are goals that address how the entity gets created (“C”), Used/Read (“R”), updated/chaged (“U”) and finally Deleted/Removed from the system (“D”)</p><p>Once you find a “missing goal,” you either add it into your actor goal list, or just explicitly put it in the out-of-scope list, or create an appropriate assumption (we’ll address those in the next article)</p><p>I won’t go into more details here, as I wrote an <a href="https://medium.com/@vedran.krizek/acceptance-criteria-demystified-48a817c2f9ca">article</a> focusing on the C.R.U.D. method, and where I explained its ins and outs.</p><p><strong>Method 2: User story mapping</strong></p><p>User story mapping is not really a formal verification method, but rather a scope discovery method that focuses on identifying end-to-end user journeys for each of the high-level goals that the system must allow for its users (a.k.a. actors) to achieve.</p><p>This method also includes identifying actors (they are sometimes called roles) and writing a short vignette about each of them, then identifying the key goals they need to achieve using the system, and then using the story mapping method to identify complete scenarios with all the important variations in which each user/role/actor achieves their key goal.</p><p>The result is a complete (and hierarchical) set of stories (which are the same thing as actor goals) that describe the system that allows all actors to achieve all of their key goals.</p><p>The brilliance of this method is that it discovers the scope in complete, end-to-end slices that can easily be added one on top of another, resulting in that progressive LOD series of images of a rose in a pot in our previous article. And that is exactly what we want.</p><p>Story mapping is, therefore, an excellent tool for discovering the bulk of the functional scope completely and consistently; however, I usually like to “run” its result through some formal method like C.R.U.D. just to make sure that I haven’t missed any important actors or goals.</p><p>That said, I won’t go into more detail here as well, since whatever I would write wouldn’t hold a candle to what Jeff Patton already wrote in his <a href="https://www.amazon.com/dp/1491904909/ref=cm_sw_r_as_gl_api_glt_fabc_943R88XEDXR0C93EARN1?linkCode=ml1&amp;tag=jefpatass-20">brilliant book</a> on the subject, and which I strongly urge you to <a href="https://www.amazon.com/dp/1491904909/ref=cm_sw_r_as_gl_api_glt_fabc_943R88XEDXR0C93EARN1?linkCode=ml1&amp;tag=jefpatass-20">read</a>.</p><h4>How to use the documented functional model?</h4><p>If we did everything right, we now have the functional part of our model documented in a way that is accessible to all project stakeholders, but that is just half of the story.</p><p>Without understanding how to use that model in a project or engineering scenario, all the effort we poured into documenting our beautiful model will remain just dead letters on the screen (or paper if you are into that sort of thing), and our effort will end up being mostly wasted.</p><p>Luckily, the “usage instructions” are very simple and boil down to this:</p><blockquote><strong>Make the individual goal statements THE DEFAULT UNIT OF COMMUNICATION on your project. And then be STRICT about it.</strong></blockquote><p>What does that mean is that there can be no discussion, formal or informal, about any aspect of system development or any detail without understanding which goal it relates to, and then using that goal as the context and framework for the entire discussion, making sure we don’t unknowingly leave its scope boundaries (*)</p><p>For example, when I’m project owner on a project and anyone from the implementation team tries to discuss anything technical with me on dailies etc. my answer is always “<em>I don’t care about implementation details, I can put my developer hat on and we can discuss it like two developers next to a water-cooler — informally, but as product owner the only thing I’m interested is which goal we’re talking about and are we struggling with it or not? If we are, then I need to understand how I can mitigate the problem or scale the goal down — but technical details are 100% in the jurisdiction of the implementation team, as that is where all relevant subject matter experts are, and I trust them completely to be better at it than I am.</em>”</p><p>I find that this attitude at first perplexes a lot of developers who are used to dumping their tech issues on the project management/ownership and then delude themselves into “but I told them we have problems,” — while the BA/PO/PM cannot really do anything with the information they got, regardless of their technical knowledge.</p><p>Luckily, I also found that if I persevere and make this goal-focused approach central (and I am strict about it), any initial resistance quickly melts away because the delivery improves noticeably, in a way that is obvious to everyone.</p><p>Now this is IMO the most important technique when it comes to using the functional model in the implementation process, but it is by far not the only one; however, for the scope of this text, which deals with requirements themselves rather than the implementation process, we’ll move on and leave more detailed discussion to some future article.</p><p>(*) <em>This is a general rule, of course, and there will always be exceptions; the key is to understand that those are the exceptions and why, and then be vigilant not to allow them to move from “exception” to “regular occurrence.”</em></p><p>This wraps up the functional part of the model layer — and also this article - and <a href="https://medium.com/p/7329238e1ac0">we’ll pick things up in the next one</a>, in which we’ll finish discussing the model layer, introduce the detail layer, and discuss the crucial connection between the two.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=fdfa73b07ac1" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Impact-driven software engineering, part 1, the functional impact and impact-focused delivery]]></title>
            <link>https://medium.com/@vedran.krizek/impact-driven-software-engineering-part-1-the-impact-and-impact-focused-delivery-ccd2ecd67e6c?source=rss-7049746239c7------2</link>
            <guid isPermaLink="false">https://medium.com/p/ccd2ecd67e6c</guid>
            <category><![CDATA[mvp]]></category>
            <category><![CDATA[agile]]></category>
            <category><![CDATA[software-engineering]]></category>
            <category><![CDATA[software-development]]></category>
            <category><![CDATA[product-development]]></category>
            <dc:creator><![CDATA[Vedran "Brko" Krizek]]></dc:creator>
            <pubDate>Mon, 12 Jan 2026 08:02:46 GMT</pubDate>
            <atom:updated>2026-02-26T11:59:38.659Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1023/1*V5WrPzFyBqvG1lplOVwxWA.png" /></figure><h3>Impact-driven software engineering: Part 1, the functional impact and impact-focused delivery</h3><h4>This is the first article in a series about an approach to designing and delivering software products that I’m calling “impact-driven software engineering”. In this article, we’ll frame the problem we aim to solve, introduce the concept of functional impact, and discuss one approach that can effectively address most of those pesky, ever-persistent issues we can’t seem to avoid encountering on every project —, the concept called “progressive impact-focused delivery”.</h4><h3>A (very long) introduction</h3><p>Have you noticed how, on every new project, we typically go in with that “we’ll do it right this time” attitude? And we know what it means too, we’ll prioritize stuff correctly and deliver those “important 20s” from 80/20 quickly and reliably, we’ll stay within our assigned budget, we’ll do a lot of prototyping to prevent costly surprises and we <strong>certainly won’t make that same mistakes</strong> we did on our last project where we slaved for a year only to release a slow-moving molases of features very few of which were actually used by our end users, oh no sir! We’ll MVP the living daylights out of this project. We’ll make the gods of agility proud.</p><p>After all, we know exactly what we need to do — all those techniques that we’ve read and heard success stories about, techniques that make perfect sense and are an <strong>obvious</strong> solution to the actual problems we experienced firsthand. It’s a wonder why we haven’t been able to implement them before. We cannot recall the exact reasons, but we guess that just the time wasn’t right.</p><p>It’s right this time around, though. We are ready.</p><p>And so we begin with our new project. We are extra diligent, we take care of every detail, we apply every good practice we know, we bring our A+ requirements engineering game, we take every detail we can identify into account, we define heaps of documentation (or create a nice backlog if that’s our thing), assign some resources in advance to prototyping efforts, decide that we’ll deliver incrementally and have a demo for our client every two weeks or so, and with our spirits high, we dive in.</p><p>And at first it goes well, everyone is positive about us pulling it off, everyone is trying their best, but you start noticing that demo sessions are rather unenthusiastic, business stakeholders seem to attend them more because they have to than because they really want to and their feedback is usually quite detached from what is being demoed — often just throwing new ideas into the ring.</p><p>You chalk it up to “the stuff we’re doing at this early stage is not really interesting for them, they’ll come around later when we’ll start delivering bread and butter features…,” so you tuck your worries away and soldier on.</p><p>In the meantime, you create a prototype for a particular technology risk you’ve identified during the design. It takes a little more resources to build than initially anticipated, but it serves its purpose, you pat yourself on the back, and feel good about finally doing things right.</p><p>Then the first “implementation surprises” happen, you find out that UI templates assume some behaviours that no one thought through, and those turn out to be tricky to implement. You find out that the framework/library you expected to use for a particular feature does not work exactly as you expected, and so the designed behavior will take more time to implement. You also start to encounter situations where what looked good on paper doesn’t really cut it “on screen” once developed. None of these issues is catastrophic in itself, but they are there, and they seem to be consistently popping up and piling up as a result.</p><p>Your internal schedule starts slipping. So you try prioritizing, but you quickly discover that for business, every feature planned is in must have category. You get the freedom to implement it however you see fit, if that will result in all features being delivered. You get a few token concessions for features that were obviously afterthoughts in the first place, but essentially you’re left to your own devices to deliver everything.</p><p>You try proposing another quick prototype to test out some confusing UX ideas and newly identified technical risks, but your suggestions are flatly rejected by the business/management with</p><blockquote>“we don’t have budget for that, we’ve already had one prototype, and that took more time than anticipated, we cannot afford it right now, let’s focus on keeping things on track instead”.</blockquote><p>You realize that business sees prototyping as “developer toys” rather than something useful.</p><p>Demos start slipping, iteration goals start being at best partially met, and iteration planning becomes more and more pessimistic and reserved.</p><p>But you still have an ace up your sleeve, the mighty MVP. You don’t have to build everything; you can build just enough to test the product hypothesis. It doesn’t even have to be a full production MVP; you can do it for a limited audience, and that would alleviate most of your issues, so you go to business/management to discuss MVP scope.</p><p>That doesn’t end well. You are met with</p><blockquote>“what do you mean MVP scope? What we have in requirements — that is MVP scope, we cannot do without any of the features we listed there”.</blockquote><p>You try to explain the concept, but to no avail; both you and the business/management end up frustrated, and you return to the team with the bad news. Morale suffers.</p><p>After that, things slowly devolve into a familiar mess, and everyone falls back to their muscle memory and grind the project to the end. The budget is overrun as usual, nobody is especially happy with the end product, and no one liked the experience of building it, but everyone is relieved that the ordeal is finally over, and everyone swears that “we’ll do it right next time, now we <strong>definitely</strong> know how.”</p><p>And the new cycle starts.</p><h3>Why does it not work?</h3><p>I bet that the introduction story feels familiar. If not, and none of that ever happened to you, then all I can say is that you are a very lucky person and should stop reading this article and go and buy some lottery tickets as quickly as you can.</p><p>For the rest of us, the question is why? Why does this keep happening? Why cannot we have those nice things, cool projects we read about, seem to enjoy? It’s probably our management/business stakeholders that don’t get it, right?</p><p>Wrong. You and I would act exactly the same if we were in their shoes.</p><p>Think about it, business stakeholders are tasked with creating a product that will have some <strong>predefined</strong> desired outcome — either by introducing a new revenue stream, optimizing some internal process, extending the user base — whatever it is, it is tangible, and it is measurable, and more importantly, <strong>it is directly tied to their bonuses</strong>.</p><p>So they know the end goal they have to meet, and for them, the system that is under design is just a vehicle to achieve it.</p><p>For the implementation team (inc. project management), though, the system is a complex machine with many moving parts, and we’re thinking about its architecture, tech stack, behaviors, etc.</p><p>The point I’m trying to make is that business and implementation teams look at the system we’re designing and implementing from two completely different points of view.</p><blockquote>Business looks at the system as an “outcome-producing black box,” while the implementation team sees it as a “technological puzzle to be solved”.</blockquote><p>What this means is that there is no shared mental model of the system under design between the different expert groups within the project, and since software engineering is a “team sport,” that is an issue. And a big one at that.</p><p>That is especially true for all situations whose outcome directly relies on the ability of business and implementation stakeholders to <strong>meaningfully</strong> and <strong>effectively</strong> work together. Good examples of such situations are prioritization in general, incremental delivery, scoping, MVP design, planning in general, and investing into experiments and prototypes, etc. — all these require that all participating parties share the same model of what is being built and then contribute their individual expertise accordingly — without a proper shared mental model of the system, that is just not possible.</p><p>We’ll discuss how to define and document the system scope in a way that addresses these issues in the upcoming article(s) in this series, but first, we’ll introduce the concept of impact, and then we’ll discuss progressive, impact-focused delivery.</p><h3>Functional impact</h3><blockquote><strong>Impact of a given software system is the difference between the world as it was just a moment before that system was released “in the wild” and the world one moment after</strong></blockquote><p>Or put another way</p><blockquote><strong>Impact of a system is a diff between two realities, one with and one without that system in it.</strong></blockquote><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*Hgvs0V98IJHCulTq31o8uA.png" /><figcaption>Spot the difference (impact)</figcaption></figure><p>It’s not unlike this “spot the difference” image above.</p><p>There are many different kinds of impact, direct and indirect, primary and secondary, functional, environmental, societal — the list goes on, but for the purpose of this text, we’ll focus on the “one impact to rule them all” — functional impact.</p><p>Any impact can be positive, negative, and neutral, but for our purposes, only the <strong>positive functional impact</strong> matters, and we’ll define it like this:</p><blockquote><strong>There is an </strong>ENTITY<strong> that can NOW achieve SOMETHING by using the system that they could NOT achieve before.</strong></blockquote><p>For example:</p><ul><li>The warehouse manager can find individual invoices by their unique number</li><li>The warehouse manager can find all invoices within a given invoice date range</li><li>The warehouse manager can find all invoices belonging to a particular vendor</li></ul><blockquote>Functional impact defines WHATS (something) and WHOS (entity) without going into details of HOWS (implementation details) — and that is something that is equally understandable to any project stakeholder regardless of their technical background.</blockquote><p>We’ll keep this concept front and center in all our upcoming articles dealing with impact-driven software engineering, and we’ll now introduce the concept of progressive impact-focused delivery as an approach that effectively addresses most issues we’ve mentioned in our introduction story — and is at least in my informed opinion, by far the best approach to software delivery for vast majority of projects(*).</p><p><em>(*) My experience is mostly biased towards web and mobile applications with complex, high-performance/enterprise backends in media/classifieds/ industries and end-user facing digital products in general. For those systems, the discussed approach works beautifully and without a hitch. However, there are some system types — in highly regulated industries or in extremely security sensitive environments, for example, where progressive delivery might not be as feasible a solution as for systems I’ve been involved with, so like with everything else, context is king, and YMMV</em></p><h3>Progressive impact-focused delivery</h3><p>Since we all know that the average exchange ratio between images and words is 1000 words per picture, we’ll use images to convey this fairly advanced concept as painlessly as possible.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/490/1*QMNPHWVyIomuyDaGZWgCig.png" /><figcaption>Our system — rose in a pot</figcaption></figure><p>The above image represents our system as a rose in a pot on a lawn. The image is composed of 130,000 individual pixels, and we can equate those with implementation details. Therefore, let’s say that this system is composed of 130,000 individual bits of impact that need to be delivered in the end.</p><p>So we can deliver the system in a number of different ways, the most “naive” — but still overwhelmingly used is what I refer to as “sequential delivery” — where we deliver the system segment by segment, where each bit is done “fully to the spec”.</p><p>The result ends up looking something like this:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*Vdf1CXXMWsexETacRdNTsA.png" /><figcaption>Sequential scope delivery</figcaption></figure><p>At 10% of bits delivered, we don’t have any meaningful impact — for all we know, the image might be just the sky. At 25% — 33%, we start seeing the top of the rose, but we’re still in quite an uncharted territory. At 50%, we have a strong idea about what the image is about (ie. system’s desired “impact”), but still, we are obviously not done. Even when 75% of the system is delivered, there is still a “there be dragons” segment at the bottom.</p><p>And now for the million-dollar question:</p><blockquote>Would you have the guts to MVP at any point in this scenario? I wouldn’t, and so it’s unfair to expect the business to.</blockquote><p>Ok, but that example is too simple, you say, we don’t just blindly deliver stuff sequentially (you’d be surprised how many teams do, but that’s another topic altogether), but rather we deliver particular, well-thought-out features and they are prioritized and all that.</p><p>Great for you, but that usually ends up like this:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*dlAebQjqUxOxTOFSqn4VkA.png" /><figcaption>Archipelago of details delivery</figcaption></figure><p>You deliver “<strong>an archipelago of detail</strong>”, each island in it being mostly functional, but with limited context, and what typically happens is that you encounter surprises where two puzzle pieces do not fit together as you expected, and also end up with “ah, that’s green, so it probably goes there” kind of sloppy thinking. Observe that at neither point (leftmost is 25% and the rightmost is 75%) you have a full system, so deciding to MVP is almost as difficult as it was in the previous example.</p><p>Furthermore, think about the scenario where you run out of development budget anywhere along the line in the previous two examples.</p><p>It’s bad, there is no recourse really except to take the losses and grind to the end, or abandon part of the desired impact with all the consequences that brings. And those are typically not nice consequences.</p><p>The sad fact is that the vast majority of all software projects are approached and delivered as depicted in the previous two images (or usually a combination of the two). Which is sad, because there is a way to do it properly.</p><p>The way was foretold by the ancient progressive JPEGs that were ubiquitous at the dawn of the internet, when connectivity speeds were measured in single-digit kb/s, and so you needed to get the impact of the image across as quickly as possible.</p><p>So here it is. This is the “proper way” to approach any project:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*p60X_WFi2-YEbUfnFjLQiQ.png" /><figcaption>Impact-focused progressive delivery</figcaption></figure><p>There is exactly the same amount of “bits of impact” delivered in this image as in the first and second one but one thing is readily apparent: even with just 10% delivered, we see the whole picture. It’s low detail for sure, and we’re not sure if the flower is a rose or some similar other one, but we see the sky, we see the pot, we understand that there is one flower and two branches with leaves, that the pot is on the lawn — stuff that we couldn’t be 100% sure about at any point on previous two images.</p><p>At 25% delivered, more brave of us would go MVP, and at 50%, even the conservative business managers would probably go for it.</p><p>Now, what does it mean when I say “10% delivered”? It’s all fine and dandy on images, but we’re not delivering images; we’re delivering working software, so how does it translate to that?</p><p>It is all about the level of implementation detail. Let’s say we’re talking about this particular impact statement:</p><p><strong>“The warehouse manager can find individual invoices by their unique number.”</strong></p><blockquote>The only non-negotiable aspect of delivery for an impact statement is that it must be demonstrably achievable.</blockquote><p>That means that for every level of detail — <strong>warehouse manager MUST be able to find an invoice by its unique number</strong> — everything else is secondary.</p><p>10% level-of-detail (a.k.a. LOD) might be just a standalone page with an unstyled input element without any validation, where the invoice number can be entered, and a button that will literally dump the content of the matching invoice on screen without any styling</p><p>Next LOD might be inclusion of that standalone page into existing admin UI (still without styling), then the next level might be some basic styling of the result and some validation, then audit logging, etc. and so on until the feature is good enough that a warehouse manager (and any other relevant stakeholder) can say “yes, this works for me.”</p><p>It’s as easy as that. As a French poet, Paul Valery once said,</p><blockquote>“No work of art is ever finished, but merely abandoned”.</blockquote><p>Keep that in mind as this is exactly the mindset we’re fostering here.</p><p>Also, think about what happens in this scenario if, for some reason, you run out of the budget mid-project.</p><p>Nothing bad will happen, as at that point in time, what you’ll have on your hands is <strong>the best possible implementation of the system that brings about planned functional impact, within the constraints of the budget</strong> you’ve had at your disposal. No one is getting fired in this one.</p><p>That is also the way to achieve that mythical “fixed deadlines in scrum” everyone typically struggles with, but that will be the subject of a future article.</p><h3>Conclusion</h3><p>I’ve been using progressive delivery throughout my career, initially by instinct rather than any formal methodology or conscious decision. The results validated the approach, as I very early found out that I was able to outperform pretty much anyone when it came to delivery — regardless of their technical level.</p><p>Let me give you an example.</p><p>When I built njuskalo.hr — Croatia’s largest classifieds platform and an extremely high-traffic system — I did it in 9 months with a team of two. I handled scoping, requirements, architecture, and development while my colleague managed UX/UI design and frontend styling. The timeline and budget seemed so impossible to everyone around us that our holding company started a betting pool on whether we’d fail.</p><p>Pretty much everyone bet against us. They all lost.</p><p>We didn’t learn about the betting pool until later, but when we did, we knew we’d done something fundamentally different. It took me nearly 10 years to understand exactly what made our approach work and to formalize it into a complete system. What you’ve read here is that system — battle-tested over 15+ years of real-world delivery.</p><p>Here’s what’s critical to understand: I didn’t succeed because I could code faster than everyone else. I’m a solid developer, but I’m not John Carmack (if you don’t know him, look him up — the guy is an entropy-defying coding demigod). Success wasn’t about how much code I could deliver per iteration, but about what I chose to code at the moment versus what I deferred for later.</p><blockquote>Ultimately, the code I didn’t write was what mattered the most.</blockquote><p>This isn’t rocket science — it’s just YAGNI and the 80/20 rule, only we applied it systematically to the entire delivery process, not just to individual features.</p><p>So there you have it — this really works, at least it does for me.</p><p>Also, as a side note, this approach, when combined with AI-assisted coding techniques, works so naturally that it feels like it was designed for that context — and I can assure you that it wasn’t</p><p>In the <a href="https://medium.com/p/fdfa73b07ac1">next article</a>, I’ll address the elephant in the room: how do you document and communicate this approach? We’ve shown how to deliver progressively, but not how to create requirements that all stakeholders can actually understand and use. That is done through a specific approach to requirements engineering that I like to call <strong>layered requirements engineering</strong>, and that is exactly what we’ll address in the <a href="https://medium.com/p/fdfa73b07ac1">upcoming article</a>, so stay tuned.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=ccd2ecd67e6c" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[AI augmented software engineering]]></title>
            <link>https://medium.com/@vedran.krizek/ai-augmented-software-engineering-41bd936d5978?source=rss-7049746239c7------2</link>
            <guid isPermaLink="false">https://medium.com/p/41bd936d5978</guid>
            <category><![CDATA[ai-augmented-development]]></category>
            <category><![CDATA[scrum]]></category>
            <category><![CDATA[software-engineering]]></category>
            <category><![CDATA[agile-development]]></category>
            <category><![CDATA[vibe-coding]]></category>
            <dc:creator><![CDATA[Vedran "Brko" Krizek]]></dc:creator>
            <pubDate>Fri, 28 Mar 2025 15:58:24 GMT</pubDate>
            <atom:updated>2025-03-28T15:58:24.609Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/800/1*TiPcrhxvHzxxoyKc2QlRBw.png" /></figure><h4>Everyone is talking about “vibe coding” and the generative AI in the context of software engineering these days — and rightfully so, as the impact on the industry is nothing short of paradigm shifting, however there is a misconception that generative AI provides non-technical people with “build me this” button and that neither IT experts nor complex development processes are really needed anymore. Nothing can be further from the truth IMO— and in this article I will try to show how AI augmentation really works in real life or at least how it works when it comes to software engineering.</h4><p>Majority of people in the IT industry that I’ve discussed this topic with broadly fall in one of two distinct camps (*) — one that partially or fully rejects the generative AI when it comes to software development due to various reasons that usually boil down to known propensity of large language models to hallucinate, and the other who embraces it, accepts it’s quirks and as a consequence typically 10 x’s their productivity.</p><p>The author of this text is (no spoilers there) a member of the latter group and the point of this article is to try to show how the generative AI can augment a real-world software engineering process. The targeted audience is pretty much anyone interested in or curios about vibe coding or AI aided code generation, but I’m especially keen to reach those who are still on the fence about introducing AI augmentation in their organization or trying it in earnest themselves. After reading this, my hope is that they will be able to make a more informed decision on this important subject.</p><p><em>(*) the division between those groups is not as black and white as depicted here as there is non-trivial overlap between the two, but generally speaking, they are distinct from each other in their general attitude towards generative AI.</em></p><h3>Introduction</h3><p>Let’s start by defining those two main terms from the article’s title. The first one is “software engineering process”, which we can define as:</p><blockquote>A process of designing, building and ultimately delivering a software solution for a given idea / problem.</blockquote><p>That leaves the term “AI augmentation”, which, in the context of this text, can be defined as:</p><blockquote>Enhancement of a particular process via integration of AI agents/assistants with the goal of significantly increasing its delivery speed while decreasing its resource requirements.</blockquote><p>Simple, right? So now, with that sorted out, let’s join those terms together and see how AI augmentation of software engineering process would work IRL, and what it is all about.</p><h3>AI augmentation</h3><p>If we take a high level look at the software engineering process, we can observe that:</p><ul><li>A number of process specific artifacts are created throughout it</li><li>The creation of those artifacts requires expert resources.</li><li>The majority of the project’s overall time and resource budget is spent on creating those artifacts.</li></ul><p>All that points to the artifacts as a very enticing integration point for the AI augmentation of software engineering process — so that is exactly where we’ll “plug our AI in”.</p><p>Such artifacts for example include high level project concept, documented functional and technical requirements, UX/UI design proposals, testable product increments, product backlog and it’s items, individual value-adding iteration goals, test scenarios and end-to-end test scripts etc. the list goes on.</p><p>We can also observe that, besides the fact that creation of mentioned artifacts require experts in various fields (system architects, business analysts/functional designers, UX/UI designers, developers, etc.) it also requires a framework within which those artifacts can be created in a controlled and deterministic fashion and in the environment where all prerequisites for each are satisfied and honored.</p><p>For example in order to create a high level project concept, functional or technical solution — the discovery process needs to be performed by appropriate experts — and only after that, the relevant artifacts can be created.</p><p>This distinction between the process artifacts and the process framework itself is important one to bear in mind, because it will guide our AI augmentation and manage our expectations for introducing AI into the overall engineering process, in particular:</p><blockquote>The role of AI in the AI augmented software engineering process is to increase delivery speed while decreasing resource requirements for the individual artifacts within the software engineering process and NOT to eliminate the need for experts within the process or to replace the process itself.</blockquote><p>After all, it is called “AI augmented” and not “AI replaced”.</p><h3>AI augmented software engineering</h3><p>Any engineering process can generally speaking be broken down into <a href="https://medium.com/undabot/how-can-the-scrum-framework-be-effectively-implemented-for-software-development-part-1-2-9e013d497507">three distinct phases — design, implementation and testing/delivery</a>.</p><p>Note that those three phases can overlap and can be performed either for the entire project scope (a.k.a. “waterfall”) or in small, incremental “value adding” chunks — which is typically what agile/scrum is all about. The point here is that those three phases are ubiquitous regardless of the methodology used.</p><p>In this chapter, we’ll go over each of those phases and list important artifacts produced within it, how they can be AI augmented, which domain experts are required for each (*), as well as what time and resource savings can be expected from the augmentation itself. We will not go into deep details as the goal here is to give the reader the general idea how AI augmentation works in real world and not to be a comprehensive or definitive resource on the subject.</p><p><em>(*) The role of domain experts is the same for every artifact — namely </em><strong><em>to Review, Complete and Integrate the work of the AI agent/model</em></strong><em> (often in multiple iterations) and therefore whenever a certain domain expert is mentioned in the remainder of the document, it is implied that their role is the one I’ve just described.</em></p><h4>Phase 1: Design</h4><p>Design process consists of three distinct components (functional, visual and technical), each with it’s own artifacts which can be significantly augmented with AI, for example:</p><p><strong>Artifact: Project concept</strong></p><ul><li><strong>Augmentation technique/approach:</strong> The draft of the problem/idea description, including the project context and organizational requirements, known risks and mitigation approaches (a.k.a. project concept) can be quickly summarized and created by an LLM based on transcript of the discovery session/interview, meeting notes etc. Furthermore, the LLM can be provided with additional instructions to make sure to avoid a set of solutions/approaches or exclusively use some others — as dictated by your organization’s standards and tech stack preferences.</li><li><strong>Required domain expert:</strong> <a href="https://medium.com/undabot/business-analyst-a-crucial-ingredient-in-a-successful-scrum-project-a94fed85d395">Business analyst/Functional designer</a> (or <a href="https://medium.com/@vedran.krizek/implementing-the-scrum-framework-as-a-robust-software-engineering-process-the-recipe-c443e8abe56a">Technical Product Owner</a>)</li><li><strong>Performance increase:</strong> In my personal experience — the required time and resources for completion of such artifact is under one hour — where without AI augmentation it would typically take 2–5 hours.</li><li><strong>Typical tools:</strong> any modern AI assistant with RAG capabilities such as ChatGPT, Anthropic’s Claude, Deepseek V3, etc.</li></ul><p><strong>Artifact: Functional solution/requirements</strong></p><ul><li><strong>Augmentation technique/approach:</strong> When writing the functional requirements, the AI assitant can provide a first draft (and review it in the context of <a href="https://medium.com/undabot/building-a-functionally-complete-set-of-user-goals-using-the-c-r-u-d-method-7b19bcf3b060">CRUD method for functional completeness</a> — or any other verification methods that your organization uses) of the actors, actor goal lists and associated acceptance criteria, use cases, business rules, etc. — based on the concept document and any supplemental information available at the time. That draft is then typically iteratively expanded until it includes the entire functional scope of the system under design. Additionally, the assistant/model can be made to follow your organization’s internal standards and let’s say produce use cases following a particular style or write acceptance criteria using Gherkin etc.</li><li><strong>Required domain expert:</strong> <a href="https://medium.com/undabot/business-analyst-a-crucial-ingredient-in-a-successful-scrum-project-a94fed85d395">Business analyst/Functional designer</a> (or <a href="https://medium.com/@vedran.krizek/implementing-the-scrum-framework-as-a-robust-software-engineering-process-the-recipe-c443e8abe56a">Technical Product Owner</a>)</li><li><strong>Performance increase:</strong> In my personal experience a fully fledged functional solution document — a.k.a. Functional requirements (including diagrams where needed) for a middle sized project (ie. a backend with some non-trivial business logic and admin UI, some integrations with internal and 3rd party APIs and a fully responsive web client) that would previously take around 20–30 hours, with AI augmentation typically takes no more than a 5–10 hours. (not counting client reviews and in-document communication in both cases)</li><li><strong>Typical tools:</strong> any modern AI assistant with RAG capabilities such as ChatGPT, Anthropic’s Claude, Deepseek V3, etc.</li></ul><p><strong>Artifact: Technical solution/requirements</strong></p><ul><li><strong>Augmentation technique/approach:</strong> When writing the technical solution document (a.k.a. Tech. requirements) the same applies as mentioned above for functional solution— ie. AI assistant/agent, directed by a Tech lead (a.k.a. System architect, etc.) can generate system architecture and tech stack proposal which is in sync with your organization’s internal standards and then that proposal can be further refined until it is ready for client review</li><li><strong>Required domain expert:</strong> Tech lead (a.k.a. system architect, etc.)</li><li><strong>Performance increase:</strong> Roughly the same as for functional requirements</li><li><strong>Typical tools:</strong> Same as for functional requirements</li></ul><p><strong>Artifact: Flow/sequence/architecture diagrams</strong></p><ul><li><strong>Augmentation technique/approach:</strong> When creating diagrams in particular, AI can provide you with an “easy button” if you use <a href="https://medium.com/undabot/visualizing-use-cases-using-mermaid-js-63a5f1b7d2f">code-to-diagram tools such as mermaidJS</a> or similar (and you really should) — as LLMs are very capable of generating the diagram code from your use cases, usage scenarios or other comparable formats.</li><li><strong>Required domain expert:</strong> Business analyst, Functional designer or a tech lead (depending on the domain the diagrams are created for)</li><li><strong>Performance increase:</strong> typical set of a couple of diagrams required for an average functional or technical requirements document can be generated and verified within 15–30 minutes, where using classic “handmade” approach (given the expertise in writing MermaidJS code) would typically take 1–3 hours.</li><li><strong>Typical tools:</strong> Specialized AI code generation/pair programming tools such as Cursor, Aider or similar, or any modern AI assistant with strong code generation capabilities (at the time of writing this article the good examples of such assistants are Anthropic Claude 3.7, Google’s Gemini 2.5 pro, DeepSeek V3/R1, etc.)</li></ul><p><strong>Artifact: “Function-less” UX/UI prototype</strong></p><p>When it comes to UX/UI design — the usage of classic AI assistants is not as straightforward as it is in the case of functional and technical solutions. Therefore that part of the design process still relies heavily on UX/UI design experts and their creativity and vision. However, that is true mostly when it comes to original and inventive design rather than the “derivative” one.</p><p>The term derivative here does not mean sloppy or bad. Think about all the login screens and contact forms you’ve seen in your life, or CRUD admin listview/editview pairs or a blog/event detailview pages, or even entire run-of-the-mill product homepages— and you’ll find that they are all essentially the same thing with different dressings. Each instance is to significant degree a derivation of other of the same class.</p><p>This is not to say that UX/UI designer’s work is meaningless and that there is no place for personal UX/UI designer’s expert touches that make one design different from another — and that is exactly where UX/UI designer comes in AI augmented UX/UI design — to provide that personal touch, that crucial 20 in 80/20 rule, in other words to make a difference with their creativity rather than spend hours and hours drawing yet another login or contact form for all possible screen breakpoints.</p><ul><li><strong>Augmentation technique/approach:</strong> In cases where we derivative design is sufficient for our project’s needs, the practice that works very well is the one where you choose a CSS/UI library (such as materialUI or tailwindCSS, etc.) and then instruct AI assistant/agent to directly code the UI that you want (somewhat similarly to using AI assistant to create diagrams via mermaidJS) using that library and following good UX/UI design practices. The result is typically quite decent right from the bat and can then be easily tweaked further by an UX/UI expert that know how to work with CSS. Although this technique blurs the line between design and implementation somewhat, it is very useful and circumvents the need for a lot of “generic” UX/UI design proposal — review — integration iterations.</li><li><strong>Required expert(s):</strong> A frontend specialist and a UX/UI specialist — as this artifact typically requires more iterations and tweaks than a simple product increment (see the next section) due to it’s visual nature and aesthetic purpose.</li><li><strong>Performance increase:</strong> A derivative design for a typical small business/service site which is fully responsive takes about a day or two to both create and code a “function-less” responsive UI. That is the amount of time required to go from having nothing but a written concept to a professional looking UI accessible on a testing/dev server and ready for a client review.</li><li><strong>Typical tools:</strong> Specialized AI code generation/pair programming tools such as Cursor, Aider or similar, or any modern AI assistant with strong code generation capabilities (at the time of writing this article the good examples of such assistants are Anthropic Claude 3.7, Google’s Gemini 2.5 pro, DeepSeek V3/R1, etc.)</li></ul><h4>Phase 2: Implementation</h4><p>The resource savings here are immense due to the fact that a group of developers is in effect replaced by an AI agent and one (typically full-stack) expert (or more if domain dictates it — but we’re talking 2–3 here, mostly part time and not 5–10 FTE).</p><p>Here are some of the most important artifacts produced within this phase:</p><p><strong>Artifact: Product increment</strong></p><ul><li><strong>Augmentation technique/approach:</strong> When building the product increment — all code (both frontend and backend) can be written by an AI assistant or agent based on the well defined and self-contained functional and technical requirements with clear and unambiguous acceptance criteria. The AI assistant can easily be made to follow internal technical and coding standards, use particular libraries and frameworks, use only particular versions of said libraries and frameworks etc. The results is then reviewed and merged by the project tech lead (or a comparable domain expert assigned with running the AI agent) in exactly the same way as it would be done for any code submitted by a human developer. The quality of requirements makes a significant difference here — so make sure that your requirements writing and scope partitioning game is up to task if you want to get the most out of AI augmented creation of this artifact.</li><li><strong>Performance increase: </strong>In my experience a low-to-mid complexity project (ie. a backend with admin UI, some business logic and API integrations and a good looking, responsive client web UI) requires about 5–10 mandays to fully build from scratch — including a full UI (see the chapter above) and a full test harness. For comparison, in most organizations I’ve worked with — this would typically be a 1–3 month project for a team of 5+ people (architects, backend devs, frontend devs, UX/UI designers, business analysts, QA specialists, etc.) so we’re talking about 20–50x improvement here.</li><li><strong>Required expert(s):</strong> Tech lead assisted by additional specialists (ie. security specialist, performance specialist, etc.) where and when needed</li><li><strong>Typical tools:</strong> Specialized AI code generation/pair programming tools such as Cursor, Aider or similar, or any modern AI assistant with strong code generation capabilities (at the time of writing this article the good examples of such assistants are Anthropic Claude 3.7, Google’s Gemini 2.5 pro, DeepSeek V3/R1, etc.)</li></ul><p><strong>Artifact: Unit/Integration test harness</strong></p><ul><li><strong>Augmentation technique/approach: </strong>When writing tests — all test code can be first written by an AI agent/LLM and then reviewed and integrated by project tech lead. The tests are typically written either based on requirements and the existing functional code created previously or generated together with the matching functional code (see product increment above) based on just the requirements.</li><li><strong>Performance increase: </strong>the time reduction here is similar to the previously mentioned case, however, the main upside here is that IRL tests are often omitted due to “we don’t have time now, we have to ship, we’ll write tests later” fallacy — and that excuse stops being viable with AI augmentation. Also, having a good and comprehensive test harness goes a long way in helping the expert running the AI agent to quickly and with confidence review the delivered code — which is crucial for the next engineering phase.</li><li><strong>Required expert(s):</strong> Automated testing specialist, QA specialist</li><li><strong>Typical tools:</strong> Specialized AI code generation/pair programming tools such as Cursor, Aider or similar, or any modern AI assistant with strong code generation capabilities (at the time of writing this article the good examples of such assistants are Anthropic Claude 3.7, Google’s Gemini 2.5 pro, DeepSeek V3/R1, etc.)</li></ul><h4>Phase 3: Testing and delivery</h4><p>We’ve mentioned some of the artifacts of the testing and delivery phase when we talked about test harness before, but we’ll cover a few more here:</p><p><strong>Artifact: End 2 end / UI test suite</strong></p><ul><li><strong>Augmentation technique/approach: </strong>The act of testing can be significantly AI augmented — especially the process of acceptance testing (confirming that the product increment indeed satisfies all acceptance criteria that define it’s solution space) which can (and should) be fully automated anyway. AI augmentation here typically boils down to creating test scripts, test scenarios and end 2 end tests that are then reviewed, completed and ran by the QA/testing expert.</li><li><strong>Performance increase: </strong>The time savings here are comparable to that of implementation phase.</li><li><strong>Required expert(s):</strong> QA/testing expert</li><li><strong>Typical tools:</strong> Specialized AI code generation/pair programming tools such as Cursor, Aider or similar, or any modern AI assistant with strong code generation capabilities (at the time of writing this article the good examples of such assistants are Anthropic Claude 3.7, Google’s Gemini 2.5 pro, DeepSeek V3/R1, etc.)</li></ul><p><strong>Artifact: Development and testing/staging environments</strong></p><ul><li><strong>Augmentation technique/approach: </strong>Setting up a staging server and deploying product increment for the demo can easily be AI augmented by having an AI create development docker setup, setup scripts for staging/test server, deployment scripts/configurations etc. which are then reviewed, completed and integrated by the DevOps expert.</li><li><strong>Performance increase: </strong>The time saving here is significant, especially for standardized environments (you really should have internal standards in your organization — as you see, they come very handy when it comes to AI augmentation) — and furthermore a lot of time is saved due to the fact that most of the “gruntwork” performed by usually very scarce and overbooked (hence slow) DevOps resources — is taken off of their hands by AI agents and so those resources can then focus on complex DevOps tasks rather than mundane ones that often take most of their workday.</li><li><strong>Required expert(s):</strong> QA/testing expert</li><li><strong>Typical tools:</strong> Specialized AI code generation/pair programming tools such as Cursor, Aider or similar, or any modern AI assistant with strong code generation capabilities (at the time of writing this article the good examples of such assistants are Anthropic Claude 3.7, Google’s Gemini 2.5 pro, DeepSeek V3/R1, etc.)</li></ul><h4>Summary</h4><p>Note that in all of the examples above — there are two things that are constant</p><ol><li><strong>AI augmentation provides significant-to-easy-button-level delivery improvements</strong> for vast majority of the software engineering process</li><li><strong>Every single artifact created by AI agent/assistant invariably *has* to be reviewed, completed and integrated by a human domain expert</strong> — even if that means just “helicoptering” over the AI agent while it does it’s thing.</li></ol><p>What it boils down to is this:</p><blockquote>AI augmentation works well and produces quality alongside the speed ONLY if it is used to build artifacts that the organization’s domain experts would be able to build themselves — given enough time.</blockquote><p>Or in other words</p><blockquote>Any deliverable MUST BE OWNED and “quality approved” by a human domain expert — even if it was built 100% with AI (otherwise you’ll loose control of the quality and end up with AI slop)</blockquote><h4>But what about hallucinations?</h4><p>Now that we talked about how to AI augment your development process, we need to address the elephant in the room, those dreaded “hallucinations”</p><p>Let’s start with acknowledging that hallucinations are indeed real, that they DO happen and furthermore, that they are here to stay, due to the very nature of the LLMs themselves — as they are in their core stochastic systems — meaning that for the same inputs they will by design provide somewhat different outputs.</p><p>That said however, hallucinations are</p><ol><li><strong>Much less of the problem than most people think</strong> due to the improvements in the models themselves — new models doesn’t hallucinate nearly as much as older (GPT-3.5 etc.) ones — they still do, but much less, and (more importantly),</li><li><strong>Hallucinations can be easily spotted and compensated for</strong> by proper prompting techniques performed by competent domain experts</li></ol><p>The key here is that second point — human expert in the loop approach.</p><blockquote>With a strong project framework, internal standards and competent domain experts, the hallucinations simply stop to be a realistic problem, becoming nothing more than a nuisance.</blockquote><p>Now that we have decent idea of where and how the AI can be used to augment and improve the software development/engineering process, let’s discuss that “strong project framework” requirement from the snippet above. In particular let’s discuss one practical framework that I’ve found to work really well in AI augmented development scenario.</p><h3>Applicable engineering framework — “micro scrum”</h3><p>I call this concept “micro scrum” and it is based on the “engineering based scrum” which <a href="https://medium.com/@vedran.krizek/implementing-the-scrum-framework-as-a-robust-software-engineering-process-the-recipe-c443e8abe56a">I’ve written about here</a> and <a href="https://medium.com/undabot/how-can-the-scrum-framework-be-effectively-implemented-as-a-software-engineering-process-4b5512b1c2cc">here</a>. In essence micro scrum is as it name suggest, a resource-light version of scrum framework where the only required roles throughout the process are technical product owner and tech lead — with associated “part-time” roles of UX/UI designer and individual domain specialists such as security experts, QA and testing specialists, etc. that join the core team intermittently when the particular project increment needs their expertise.</p><p>The process itself is mostly unchanged from <a href="https://medium.com/@vedran.krizek/implementing-the-scrum-framework-as-a-robust-software-engineering-process-the-recipe-c443e8abe56a">what is described here</a> , the main difference being that the typical team is much smaller — it extreme cases it can even be “scrum of one”, but in the typical scenario it is composed of at least two permanent members — technical product owner and a tech lead with a couple of non-permanent (but very important) roles, lead by the role of the UX/UI designer. The added “freebie” of this setup is that due to it’s size (and the implicit requirement for all permanent members to be mature experts), achieving self-organization is much easier and more feasible than for your classic scrum team composed of various individual with varying levels of expertise and social skills.</p><p>The events (especially their <a href="https://medium.com/undabot/how-can-the-scrum-framework-be-effectively-implemented-as-a-software-engineering-process-4b5512b1c2cc">expected outcomes/goals </a>) and the framework remain unchanged except for:</p><ul><li>In case of the minimal team, there is no need for dedicated scrum master anymore — the responsibilities of that role can be taken by technical product owner. That does not mean that you cannot still have scrum master if you like/need, just that in the case of the minimal team it is no longer mandatory.</li><li>Effort estimating is done WITH the help of an AI assistant/agent — acting as a separate expert, but ANY proposed estimate coming from it must explicitly be approved by both the tech product owner and tech lead</li></ul><p>That is more or less that — no further changes are needed really, as the goal and the purpose of each individual event and the iterative process in itself remain unchanged from the base process mentioned before. We’re still producing the software using the best know approach for doing so, just that most of the “heavy lifting” or “grunt/grind” team resources are replaced by the AI agents/assistants</p><h3>Conclusion</h3><p>The effects of AI augmentation of the classic/legacy software engineering process are (in my opinion at least) both groundbreaking and industry-changing as the theoretical reduction in the amount of needed “general coder” resources is immense.</p><p>As a consequence, a good AI augmented team can typically deliver ten times (or even more — depends on the domain) value in the same time frame as the classic one, and do so with a fraction of resources. This affects the price of creating software solutions by lowering the internal development costs drastically, and as a consequence “democratizes” software solutions by making them available to individuals and organizations who might have had good product ideas, but lacked funds for (let’s be frank about it — expensive) design and development.</p><p>Those are all positives in my view.</p><p>When it comes to challenges — here are the few that I didn’t have time address in more detail due to size constraints of this (already too long) article:</p><ul><li>The AI assistants are biased by the data they were trained on, that can lead to them pushing obsolete practices or library versions in their responses unless guided explicitly (that is where things like Cursor rules come in handy)</li><li>With generative AI, the IT security aspect of your project is easy to get to the point where it “looks fine” while it is in fact incomplete or insufficient. IT security is one area where you truly need to have strong IT security expert/practices included in the “AI loop” — as the potential exploit impact is significantly larger than for other aspects of your system.</li><li>One of the most alluring features of LLMs and AI agents in the context of software development is that they are deceptively easy to try naively and get results that look decent, while at the same time, it requires significant expertise to ensure that the quality of those results is not compromised.</li><li>It requires significant expertise to integrate AI augmentation in a scalable and reliable way into an existing processes your organization might have in place — as those processes typically needs to be optimized and perform well BEFORE you try to introduce AI into them</li><li>Like any other skill, your development skill will atrophy if not used — so it requires self discipline to stay in “coding shape” — which is something you need to be in if your role is to review, complete and integrate generative AIs output into non-trivial production systems</li><li>The experts I’m mentioning in this article do not come “dime a dozen” and are instead typically hard do source as they need to posses much more than mere technical ability (anyone who has ever worked in IT resource hiring will know what I’m talking about here)</li></ul><p>So to sum up this very long article into some take-away points:</p><ul><li>AI augmentation is not a silver bullet or a magic “build me a software solution” button that can be pressed just as well by a seasoned IT expert as their uncle or a random “man on the street”.</li><li>AI augmentation DOES NOT eliminate the need for experts, but it does significantly reduce the need for “generic developers” and the number of individual experts you typically need for any given field.</li><li>There are parts of the holistic engineering process that require humans (ie. discovery, reviews, demos, etc.) and are therefore not suitable for AI augmentation</li><li>AI augmentation DOES NOT replace the engineering framework with a magic “design&amp;build” button but rather vastly improves the delivery of artifacts WITHIN that engineering framework</li><li>When properly integrated — AI augmentation DOES offer game-changing productivity boosts — on the magnitude of ten or more for most domains — web development especially.</li><li>If you struggle with delivery of your “legacy” engineering process, just “slapping some AI” on it will make it fail more, the PREREQUISITE for reliable and effective AI augmentation of your process of choice is that that particular process is implemented correctly in it’s “non-augmented” form. Or put another way — your legacy process should deliver already — and then and only then the AI augmentation will make it deliver much more.</li><li>Any deliverable MUST BE OWNED and “quality approved” by a human domain expert — even if it was built 100% with AI (otherwise you’ll loose control of the quality and end up with AI slop)</li></ul><p>That is about it, in this article, we’ve only scratched the surface, and since generative AI landscape develops at such breakneck speed, it is debatable what and where the surface actually even is.</p><p>With all that said, my experience with AI augmented software development is extremely positive, I see it as phase transition from handcrafted to “machine manufactured” software engineering and if you want to try it in your organization, I strongly encourage you to do so. If you need help with it — reach out and I will most likely be able to help.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=41bd936d5978" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Implementing the Scrum framework as a (robust) software engineering process - The recipe]]></title>
            <link>https://medium.com/@vedran.krizek/implementing-the-scrum-framework-as-a-robust-software-engineering-process-the-recipe-c443e8abe56a?source=rss-7049746239c7------2</link>
            <guid isPermaLink="false">https://medium.com/p/c443e8abe56a</guid>
            <category><![CDATA[agile-methodology]]></category>
            <category><![CDATA[software-development]]></category>
            <category><![CDATA[scrum]]></category>
            <category><![CDATA[scrum-framework]]></category>
            <category><![CDATA[business-analyst]]></category>
            <dc:creator><![CDATA[Vedran "Brko" Krizek]]></dc:creator>
            <pubDate>Wed, 13 Nov 2024 16:02:59 GMT</pubDate>
            <atom:updated>2024-11-14T15:31:47.611Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="Image by fanjianhua on Freepik" src="https://cdn-images-1.medium.com/max/1024/1*65kDIaAH37XD_nbKRvXr7Q.jpeg" /></figure><h4>In <a href="https://medium.com/undabot/how-can-the-scrum-framework-be-effectively-implemented-for-software-development-part-1-2-9e013d497507">part one</a> of what seems to be shaping up to be a “trilogy” I have talked about the origin of scrum and the basic engineering principles and in <a href="https://medium.com/undabot/how-can-the-scrum-framework-be-effectively-implemented-as-a-software-engineering-process-4b5512b1c2cc">part two</a> I’ve presented how the main scrum ceremonies/events “map” to those principles and what their input and output should be in that context. Now it’s time to put it all into practice.</h4><h3>Introduction</h3><p>The key takeaway point so far is this.</p><blockquote>If you DON’T honor core engineering principles when you implement the scrum framework within your organizational or project context, you are effectively and reliably positioning yourself for failure.</blockquote><p>In such a case, you will be doing only a little more than throwing the dice and hoping the self-organizing team will magically figure things out. This CAN (and occasionally does) happen with a good enough team, but even then it’s uncommon and most certainly is not guaranteed. On top of it, even if you get lucky, that team will instinctively fill any blanks your scrum implementation left in the engineering process with their interpretations, and therefore to some degree will be doing your job.</p><p>So, what about the “canonical” Scrum implementation? Aren’t the issues like the one I’ve just mentioned already addressed there? Well, in theory — yes, but unfortunately, in practice, they are not.</p><p>I have two main “gripes” with that “canonical” version: the role of the product owner and the notion of a self-organizing team. I find both overly optimistic assumptions and, as a consequence, inadequate solutions to real engineering challenges.</p><p>In the “wild,” teams are not by default “self-organizing” (*), and Product owners are typically humans. As such, they are very unlikely to reach the golden standard of product ownership set by that scrum role—one where they need to both be business savvy and think in business terms while at the same time possessing most of the skills of a typical business analyst or functional designer.</p><p><em>(*) Many coaching methods are designed to fix this. Terms like “empowering the team”, etc. are often thrown around as solutions. Unfortunately, in my experience, none of those techniques fix the core issues and transform the “normal” team into a truly self-organizing one. The effects are usually not zero, but they are closer to “feel good” than to “effective” in my opinion. And I have a sneaking suspicion that a lot of product sponsors who, well, sponsor all that effort — will agree with me on this one</em></p><p>As a result, typical “generic” scrum implementations tend to fail. Their mode of failure is that the delivery of actual value is unreliable, or at least extremely dependent on team structure and individual (underdefined — but hopefully present) skills and affinities.</p><p>The whole point of this “trilogy” of texts is to present one particular way that I’ve found (**) to work in real life, with real teams, and which is specifically designed to address those problems I’ve mentioned. In particular, it aims to ensure that:</p><ol><li>All core aspects of the “generic” (software) engineering process are observed</li><li>The iterative delivery of value is consistent and reliable regardless of the team’s experience (bared extremes)</li><li>The most underdefined/problematic parts (in my opinion, of course, YMMV) of “canonical” scrum implementation are addressed and associated risks are mitigated — namely the “omnipotent” role of the Product Owner and that elusive “self-organizing” team</li><li>It scales well.</li></ol><p>To put it another way, this implementation aims to ensure that the effect of the “real world” implementation team will be limited PRIMARILY to its velocity and NOT its ability to reliably deliver value. (*)</p><p><em>(*) There are limits of course, you cannot just throw in a group of juniors and expect miracles, but even in that case, you’d still have a transparent process without any “black boxes” and would therefore be able to get some value out of it.</em></p><p><em>(**) I’ve been in the IT industry for over 30 years now and have been in the position to participate in the development of mid-to-large software systems in almost all relevant roles, from developer, system architect, business analyst, project manager, product owner, functional designer, requirements architect, CTO, etc. (except as a UX/UI designer, I’m rather terrible with that), so I had a privileged position to observe what works and what does not from all relevant vantage points.</em></p><h3>“The recipe”</h3><p>For the purpose of this section, we’ll assume “agency setting” (*) — meaning that most of the roles will be on the “agency side” with only a few on the “client-side”. All roles will be accordingly labeled.</p><p>I’ll present the concept by listing all of the important and newly added custom roles, their expected skills and responsibilities, and finally list some tips/key points on particular aspects of the process you need to keep in mind — and which often get neglected.</p><p>Also except where I’m explicitly stating that the role is custom or modified from the “canonical” Scrum role, it is assumed that the role is implemented in a standard Scrum fashion.</p><p>It is also assumed that all Scrum ceremonies and events are being followed and that they are performed in a way <a href="https://medium.com/undabot/how-can-the-scrum-framework-be-effectively-implemented-as-a-software-engineering-process-4b5512b1c2cc">suggested here</a>.</p><p>In other words, this approach extends the standard scrum implementation rather than replacing it from the ground up.</p><p><em>(*) This approach works just as well in the in-house team/startup scenarios, as all principles and skills/responsibilities apply — the only difference is that there wouldn’t be much distinction between the agency/client side of things.</em></p><h4>Scrum master</h4><blockquote>An “MC” of the scrum implementation. Responsible for ensuring that all of the implementation’s elements are done well, producing the results they are supposed to and have all the inputs they need.</blockquote><p>Agency side. Standard scrum role, all the standard requirements for this role apply with the additional emphasis on:</p><ul><li>Strong understanding of this particular implementation of the Scrum framework as their main role is to ensure that the implementation and the framework are followed and each of the ceremonies produces expected results — as <a href="https://medium.com/undabot/how-can-the-scrum-framework-be-effectively-implemented-as-a-software-engineering-process-4b5512b1c2cc">described here</a></li></ul><h4>Technical product owner</h4><blockquote>Owner of the backlog and functional scope. The “the buck stops here” person for all topics related to backlog item quality, functional scope, value-centered scope partitioning and iteration goals setting, and for all topics related to the requirements in general.</blockquote><p>Agency side. A custom role whose required skill set <a href="https://medium.com/undabot/business-analyst-a-crucial-ingredient-in-a-successful-scrum-project-a94fed85d395">significantly overlaps that of a business analyst or a functional designer</a>.</p><p><strong>Required skillset:</strong></p><ul><li>Strong understanding of scope discovery/validation techniques such as story mapping, impact mapping, user interviews/ surveys, lean inception, rapid prototyping, etc.</li><li>Strong understanding of documenting requirements using standard formats such as user stories use cases, acceptance criteria (either gherkin or free-form), etc.</li><li>Strong understanding of <a href="https://medium.com/undabot/solution-design-first-part-2-the-functional-design-82f25f2a9b8">functional design principles</a></li><li>Strong ability to quickly slice any functional scope into individual, adjacent, value-adding segments</li><li>Strong understanding of general engineering principles (needed for managing the “holistic” engineering process through project backlog)</li><li>Strong understanding of specifics of developing solutions that the organization produces (ie. if you are building native mobile apps, you need to understand how the mobile apps are built and what their constituent parts are)</li><li>Strong understanding of the <a href="https://medium.com/undabot/how-can-the-scrum-framework-be-effectively-implemented-as-a-software-engineering-process-4b5512b1c2cc">Scrum process</a> and especially its <a href="https://www.mountaingoatsoftware.com/books/agile-estimating-and-planning">estimation and planning</a>/commitment techniques</li><li>Strong understanding of the progress monitoring techniques (ie. burndown charts, etc.) applicable to scrum context</li><li>Strong communication and argumentation skills</li></ul><p><strong>Responsible for:</strong></p><ul><li>Ensuring that the backlog faithfully reflects business requirements/goals (discovery — with Business product owner) at all times during the project duration</li><li>Ensuring that the individual backlog items are of good enough quality for effective refinement and planning sessions (ie. that they conform to the definition of ready) (requirements)</li><li>Ensuring that the top of the backlog is sliced so its size matches the requirements for the planning session and DoR (ie. that the individual stories are small enough)</li><li>Ensuring that the individual iteration/sprint goals are well-defined and that they deliver demonstrable value</li><li>Ensuring that the backlog reflects the relevant details of the engineering process as performed within the organization</li><li>Ensuring that the delivered iteration is evaluated against its goal and any discrepancies or new insights are added to the backlog</li><li>That the burndown charts (or equivalent progress/total known scope tracking techniques) are produced and utilized in planning/prioritization</li></ul><p>If you want stable delivery, then one of the crucial (but not the only one) prerequisites is that the backlog must truly serve as a single source of truth for the known project scope, and the Technical Product owner is there to ensure that is the case.</p><blockquote>The technical product owner OWNS the product backlog in every sense of the word except for business-related prioritization of its PBIs.</blockquote><p>In the context of core engineering principles, the technical product owner ensures that the “what we need to build?” step of the process is done quickly, completely, and competently and that as a consequence the “how will we build it?” step can be performed with the best possible quality raw input/ingredients.</p><h4>Tech lead</h4><blockquote>Owner of the system architecture and guardian of the technical standards and good practices. The “buck stops here” person for all topics related to the technical solution for the system under development.</blockquote><p>Agency side. A custom role that ensures that the elements of the “self-organizing team” expectations which are crucial for the engineering process will be met. For example, those include things such as that the technical solution (*) is there when needed by the implementation team, that the internal standards and good practices are observed, and that the system architecture remains consistent and evolves in a controlled fashion, etc.</p><p><strong>Required skillset:</strong></p><ul><li>Competent system architect</li><li>Strong understanding of typical architectures and design patterns for the type of systems that the organization builds (ie. if the organization builds web systems, then they need to understand the architecture of those classes of systems deeply)</li><li>Strong problem-solving and decision-making skills (needed to effectively resolve any “ties” in a way that is well-argued and non-aggravating to other team members)</li><li>Strong collaborative leadership and communication skills (needed to ensure that the individual team members contribute their expertise freely and willingly)</li><li>Strong understanding of the organization’s tech. standards</li></ul><p><strong>Responsible for:</strong></p><ul><li>Ensuring that the internal tech standards are observed</li><li>Ensuring that the technical solution (a.k.a. “architecture”) (*) for the system under development is clear and discussed during a planning session for each iteration and that the solution is consistent, meets the appropriate quality level, and is in tune with the organizational and global good practices</li><li>Ensuring that the technical solution (architecture) is evolving together with the implemented product</li><li>Ensuring that any member of the implementation team can easily get answers about the technical/architectural aspect of the implementation process — NOT INCLUDING the questions answered by their expected knowledge level/seniority (ie. “how should I structure this class?”, etc.) and the internal standards (ie. “do we write automated tests or not, and if we do, what code coverage we aim for?”, etc.)</li><li>Making “on the spot” architectural decisions when such action is unavoidable</li></ul><blockquote>The tech lead is NOT responsible for creating the entire tech solution himself or herself but rather for ENSURING that *there is one* and that it is consistent, complete, in tune with internal standards and good practices, and easily accessible to the implementation team. In other words, they OWN the tech solution.</blockquote><p>Also just as an additional note — The tech lead is NOT responsible for creating tasks for members of the implementation team, and the Tech lead DOES NOT necessarily be one of the developers on the project (but it is usually better and more convenient if they are)</p><p><em>(*) Tech solution is NOT a list of internal technical standards and good practices, tech solution is “</em><strong><em>the answers to all of the questions that the competent developer might have about the system architecture and its components that are not covered by internal standards and well-known good practices</em></strong><em>”</em></p><h4>Implementation team</h4><blockquote>A group that takes an iteration’s scope (a.k.a. requirements/backlog items) and an iteration goal as their input, and then builds and, at the iteration’s end, delivers product increment which implements that scope while ensuring the predefined quality level set by the organization</blockquote><p>Agency side. A standard scrum implementation team with standard responsibilities and skills expected from scrum developers. Besides classic expectations, on top of those these are the additional skills and responsibilities they should possess.</p><p><strong>Required skillset</strong></p><ul><li>Deep understanding of the estimation process in story points — what is it for, why there is not, and can be no “formula that converts hours into story points” when the story points make sense and when they don’t, etc.</li><li>Understanding of the estimation and planning process in a “waterfall” context (needed for reliable individual iteration planning and commitment)</li></ul><p><strong>Responsible for</strong></p><ul><li>Arriving at the commitment for the iteration goal in a controlled, informed, and meaningful fashion</li><li>Delivering the iteration result they committed to (product increment) honoring all technical and quality standards (*)</li></ul><blockquote>The effects of an inexperienced development team SHOULD NEVER be poor quality of iteration results or regularly missed sprint goals but rather just suboptimal velocity.</blockquote><p>The role of the technical Product owner and the Tech lead is to ensure that that is the case.</p><p><em>(*) this holds true in the case where the technical product owner, business product owner, and Scrum master have consistently removed all daily obstacles they faced throughout that iteration (if any) and provided there were no major unforeseeable impediments (ie. flu season decimates the team, etc.)</em></p><h4>Business product owner</h4><blockquote>The “buck stops here” person for all matters related to business aspects of the system being built. Responsible for business-related prioritization and for keeping project direction aligned with the business vision/objectives</blockquote><p>Client/Business side. This is a simplified “canonical” Product owner role, modified in the way that their scope of work matches what your typical product owner in the real world is good at, and the things that they typically are not — are extracted into the role of Technical product owner.</p><p>The Business Product owner handles all the business requirements, product strategy, business-related prioritization, etc. This person does not have to have any particular set of technical or requirement writing skills, but they need to be able to make decisions quickly and be responsible for project direction and vision.</p><blockquote>The Business and Technical product owners form a “perfect pair” that together can realistically provide all the skills implicitly or explicitly expected from the classical, “holistic” product owner.</blockquote><h4>Other roles</h4><p>Client/Business side. I try my best (I’m usually “playing” the role of the technical product owner) to have a product sponsor on all of my projects and to ensure that that person is included in every couple of demo sessions for a completed iteration —especially when a piece of functionality I know has a significant value for them is completed.</p><p>I found that doing that has multiple benefits (provided that you did everything else as defined in this document and as a result, your team is delivering value reliably and regularly), one of them is that it removes the “fog of war” from the business perspective, and when the business managers see the delivered value (don’t confuse this with delivering code or other purely technical artifacts, you can deliver the same amount of code and deliver either a lot of value and none at all) they usually relax and right there and then drop any tendencies to micromanage that might’ve had. The other is that it’s great for the team morale and awareness of their role in the wider picture of the product in a global/market context to be able to show value to the product sponsor and get their feedback — which is (if you deliver *value*) typically positive and constructive.</p><h3>A few additional implementation tips</h3><p>The roles described above are the core part of this particular Scrum implementation “recipe”, and are enough in themselves if all of the listed skills are there and all the listed responsibilities are being observed.</p><p>What follows here is a list of “implementation tips”, in no particular order, that I’ve found make a difference and prevent some common pitfalls and issues.</p><ul><li>Estimate stories in story points, and don’t succumb to “we’ll do it in hours because that’s what we understand” — this is wrong and I’ve yet to see the implementation where that approach works in a sense that you still have all other benefits of the Scrum process.</li><li>Estimate during the refinement session, that ensures that everyone will actually participate and not just go through the motions.</li><li>Don’t try to find a magic formula that converts SPs into MHs. There isn’t one. The relationship between the two IS proportional, but it’s NOT linear</li><li>Commitments matter, hold the team responsible for them and treat missing sprint goals as an “honestly undesirable outcome” rather than, “everyone fails, no big deal, let’s have a retrospective and better in the next sprint”. That DOES NOT MEAN military discipline or anything like that, but I’ve seen too many teams who treat missed sprint goals in a very off-hand way — this is wrong, you don’t have to beat yourself about it, but be aware that it is a FAILED sprint — and that is and should never be considered anything but a bad outcome without trying to sweeten it by finding a “silver lining” in it.</li><li>Technical tasks are 100% in the domain of the implementation team, the smallest unit of communication outside the implementation should be a story and its ACCs (in other words a story PBI)</li><li>NEVER discuss tech tasks on any scrum event (dailies, refinement, etc.) EXCEPT when there is a clear impediment related to one and when the Scrum Master, Technical, or Business Product owners can help mitigate it (ie. the task might be to “set up a docker container for the database” and perhaps that requires external DevOps resources that the team has problems getting— that is something that the SM/PO can address and in those cases, it’s perfectly fine to talk about technical details/tasks)</li><li>Never lose track of the story on account of its technical tasks — if you do so, you will find that you’ll be herding the cats in the sense that tech tasks will keep getting finished, and new ones will keep appearing in their place. You’ll be developing like your hair is on fire — but somehow the story will never be completed, as there will always be “just a few more tasks” and as a consequence no demonstrable value will be delivered and the project will stall. When you mandate that only stories matter — that changes things a lot, for example when you encounter issues that might be technical — but still talk in the context of the story, you’ll be able to perhaps slice out the “tricky bit” in a way that the remainder and “the bit” individually have value and deliver the core and put the tricky bit back into the backlog — in a way that is still transparent and understandable to non-tech person.</li><li>Never forget that the technical tasks have no VALUE of their own except in the context of their parent story, they are IMPLEMENTATION details for it and therefore should be completely outside the scope and interest of the scrum master, or product owner(s)</li><li>Creating technical tasks is 100% the implementation team’s responsibility. They can do it however they like, but they are not to be used in any scrum events except in the cases described before. This is how the “freedom with implementation details” and “self-organizing” are manifested.</li></ul><h3>Summary and conclusion</h3><p>To sum up, the two biggest flaws in “canonical” scrum, in my opinion, are the unrealistic scope of the implicitly expected skillset for the role of a product owner and the notion of (and the expectations from) a self-organizing team.</p><p>The issue here is that both of these roles are crucial for ensuring that the engineering process underlying the Scum implementation is being implemented adequately. Therefore if any of these two roles do not “rise to the occasion” — and it seems that to expect them to do that by default is quite a tall order - then the delivery will suffer as a consequence, no ifs or buts about it.</p><p>Therefore this implementation recipe is designed to address these two issues, The first one is addressed by introducing the technical product owner role which introduces a professional with a very specific set of skills into the mixture that ensures that everything up to individual iteration planning will be done in a way proscribed by scrum — ie. it will be sliced, and diced and prioritized by business value and also will be of professional level quality, and will be done quickly. The second is addressed by introducing the tech lead, who is there to mitigate the remaining risks inherent in a “self-organizing” team.</p><p>This recipe does not pretend to be the “only way” or the “best way” or even an especially brilliant one, it is just a “one way that works IRL”. My message to you is this — if you don’t like this recipe, try to come up with your own, since in my opinion, one thing that is certain and well proven to not work very well, is to slap together a bunch of developers, have them read the agile manifesto and canonical scrum materials (or blindly certify them) and expect that they will self-organize and start reliably delivering value simply because you added (certified or otherwise) scrum master, coach, and product owner into the mix and everyone follows the Scrum ceremonies to the best of their abilities.</p><p>That just does not work unless we’re talking about experienced and competent people with good communication and organization skills, and the fact of life is that unless we’re talking about large organizations with a lot of money and access to a good-sized talent pool — that is just not the case. You will be working with a motley crew of average developers with often “iffy” communication and organizational skills. The system presented here aims to ensure that you can have a reliable iterative delivery within the scrum framework in those conditions as well.</p><p>It needs to be said that this approach introduces new roles in the framework that are both crucial and require skill and expertise to do properly — but the upside of that is that those roles and skills are (hopefully) well-defined, explicit, and known in advance. The reasoning is that it’s much more feasible and scalable to a have couple of experts and a “real-life” implementation team than to rely on underdefined roles and unrealistic expectations of the canonical Scrum framework and hope you’ll somehow end up with “the right mix that will work this time around”.</p><p>However, there are limits and sometimes you need to acknowledge that the team you have at hand is just not cut for the job, in other words, it might be true that “this is not the team you’re looking for” and there is no recipe that will change that, but for most other situations, the one described here should work just fine.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=c443e8abe56a" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[How can the Scrum framework be effectively implemented as a (software) engineering process?]]></title>
            <link>https://medium.com/@vedran.krizek/how-can-the-scrum-framework-be-effectively-implemented-as-a-software-engineering-process-4b5512b1c2cc?source=rss-7049746239c7------2</link>
            <guid isPermaLink="false">https://medium.com/p/4b5512b1c2cc</guid>
            <category><![CDATA[software-engineering]]></category>
            <category><![CDATA[software-development]]></category>
            <category><![CDATA[scrum-framework]]></category>
            <category><![CDATA[agile-development]]></category>
            <category><![CDATA[scrum]]></category>
            <dc:creator><![CDATA[Vedran "Brko" Krizek]]></dc:creator>
            <pubDate>Wed, 16 Oct 2024 12:19:39 GMT</pubDate>
            <atom:updated>2025-03-25T17:15:16.847Z</atom:updated>
            <cc:license>https://creativecommons.org/licenses/by-nc/4.0/</cc:license>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*uZnYC1pvo-7dgldp9Iu8Hg.jpeg" /></figure><h3>How can the Scrum framework be effectively implemented as a (software) engineering process? (part 2/2)</h3><h4>In the <a href="https://medium.com/undabot/how-can-the-scrum-framework-be-effectively-implemented-for-software-development-part-1-2-9e013d497507">first part of this article</a>, we’ve discussed the foundations of the engineering process and argued that the implementation of Scrum (and other Agile frameworks) presupposes a strong understanding and experience with its core principles. We’ve also argued that most of the “classic” Scrum-related issues arise when that is not the case. In this article, we’ll try to show one way the Scrum framework can be implemented if we are to honor those engineering principles.</h4><h3>Mapping Scrum onto the “bare-bones” software development process</h3><p>Now that we <a href="https://medium.com/undabot/how-can-the-scrum-framework-be-effectively-implemented-for-software-development-part-1-2-9e013d497507">have some idea of the core concepts of the software development process</a>, let’s figure out how we can implement the Scrum framework while keeping those concepts firmly in our focus.</p><p>The way we’re going to do this is that we’ll go over standard Scrum ceremonies/events such as Refinement, Planning, and Review/Demo and propose what should be their inputs, what we should expect as their result, and what are their important “internal bits” and how they should be performed to preserve the link to the foundations of the engineering process.</p><p>We’ll skip optimization-oriented ceremonies such as retrospectives as their relation to the core aspects of the software development process is more of a secondary one. That does not, by any means, suggest that they are “lesser events”, but for our discussion, they do not illustrate the point I’ll be trying to make as much as refinement, planning, and review do.</p><p>So let’s see what we’re working with here.</p><h3>Backlog refinement</h3><h4>Required Input</h4><ol><li>Unrefined but prioritized backlog.</li></ol><p><em>At this point, there should be something in the backlog, and that “something” in a canonical Scrum should be created and prioritized by the product owner. The level of detail of the PBIs is typically low - typically made from just user stories with perhaps a couple of high-level ACCs thrown in, and the functional scope is usually incomplete.</em></p><h4>Expected Output</h4><ol><li>For each of the input PBIs, there must be either a fully functionally defined and <strong>estimated</strong> “original” PBIs or a set of fully defined and <strong>estimated</strong> smaller PBIs that fully cover the scope of the original PBI.</li></ol><p><em>All resulting PBI should conform to the “definition of ready” convention, (and yes, you should have one, either explicitly or implicitly).</em></p><h4>The purpose and the implementation details</h4><p>The main goal of the refinement session is to ensure that there is at least one (but it really should be more than that — two seems to be a sweet spot for me, but YMMV) iteration worth of “ready-for-planning” PBIs at the top of the backlog.</p><blockquote>In a nutshell, the raw, underdefined PBIs <strong>enter</strong> the refinement session and the fully defined, “ready-for-planning” PBIs come out of its “other end”.</blockquote><p>The part of the engineering process that the refinement maps to is the <strong>“What does that piece of software need to accomplish?”</strong>.</p><p>I want to draw your attention to the fact that I’ve highlighted the word “estimated” in the definition of what the output of the refinement session should be. You might have a bunch of reasons why you’d prefer to estimate as a separate event or as a part of another event - and here is the reason why that is typically a bad idea (unless you know what you are doing and are aware of risks and know how to mitigate them).</p><p>One of the main goals of the refinement session is to figure out all the important details (acceptance criteria, assumptions, etc.) about the refined PBI’s scope — which is essential if the backlog is to be a single source of truth - and to achieve that goal in collaboration with the team so you can leverage their combined knowledge, creativity, and individual insights.</p><p>The other, closely related goal is to make sure that the team as a whole truly understands the refined scope, and the usual expectation is that this will happen automatically as the entire team was involved in discussing and defining the details of the refined PBIs in the first place.</p><p>Sadly, that’s often not the case with your “typical” team - what will usually happen is that (mostly) everyone will simply nod their head in agreement during the refinement discussions, have few or no questions, and everything will be clear to them - until the development starts and then there will be a bunch of “surprises” and “but we thought that…” moments (sounds familiar?).</p><p>You can utilize a bunch of people management techniques to try to “open the team up”, empower them, etc. — but in my experience, that usually has limited results and does not work for everyone, and what’s more important, there is much much simpler and more effective way to “enforce” active listening and participation — namely the estimating.</p><p>The strategy works like this, after the “ok let’s discuss this story” part of the process, you ensure that you go through an estimation process where <strong>everyone (*) </strong>needs to essentially “summarize their understanding of the scope by providing a number” then, like by some kind of magic, everyone “wakes up” and suddenly have a bunch of questions, assumptions they’d like to discuss and clarify, suggestions, worries etc - everything you really wanted in the first place, but what (in my experience) you simply won’t get without making sure that scope refinement and estimating are packaged together.</p><p>YMMV of course, but this approach works for me and I’ve used it with good results for years now.</p><p><em>(*) that is another important point — everyone should pitch in when estimating — because that is the most effective way of dealing with individual estimation biases, and why estimating with story points works rather well even for non-technical people</em></p><p>So the estimating serves two purposes - the first and obvious one is to get estimates so that you can somehow gauge whether you have enough refined material on top of your backlog for at least one upcoming iteration and the second one is to make sure that team will be truly involved (and have “skin in the game”) in the scope discussion process and end up sharing the same mental model of required scope.</p><blockquote>The process of estimating ensures team’s active participation in refinement beside just yielding the actual estimates in story points</blockquote><h4>The frequency</h4><p>You can have as many (or as few) estimation sessions as you need to ensure that on the date of the planning session (and you can have only one of those per iteration) you have (at least) enough of the “ready-for-planning” material at the top of your backlog so that the team can plan and commit to the scope of the upcoming iteration.</p><h3>Iteration (sprint) planning</h3><h4>Input</h4><ol><li>(at least) “One iteration worth” of prioritized backlog consisting of PBIs meeting (implicit or explicit) definition of ready (ie. estimated, refined, etc.) — or in other words, a product of a proper refinement session(s)</li><li>An iteration goal suggested by the product owner</li></ol><h4>Output</h4><ol><li>Refined/updated or confirmed iteration goal</li><li><strong>Realistic and objective</strong> commitment to the delivery of the goal by the entire team as a unit (ie. there should be no “frontend only goal”, “backend only goal”, etc.)</li></ol><h3>The purpose and the implementation details</h3><p>The main goal of this event is for the team to discuss and plan the iteration in detail and commit to its scope, in (dare I say it?) Waterfall way.</p><p>Before you start sharpening your pitchforks and go to check whether you have some tar and feathers left over from the last time someone mentioned the word “waterfall” while talking about scrum - hear me out.</p><p>For the product owner to be able to plan anything, he or she must know that the team’s commitment to the iteration’s scope and goal can be “taken to the bank”. Otherwise, they will be unable to neither plan nor steer the project in any sensible fashion and are reduced to mere passive observers of whatever happens and can only hope that the “team will somehow manage it”.</p><p>That never ends well. Even with a fairly competent and well-meaning team.</p><p>Consequently, for the team to commit to the scope in any way that is not a variation on the “we believe in ourselves, we feel empowered and if we all pull together we can do it!” substitute for a real commitment, they need to at least:</p><ol><li>Dissect the scope into implementable pieces taking into account different roles and expertise needed for each (ie. this is the time to start discussing what is frontend and what is backend work, etc.)</li><li>Figure out and agree on technical solutions for the iteration’s scope, where such solutions will ensure optimal technical quality and adherence to the level of quality the organization promises to deliver — the level of detail they need to go into is reversely proportional to the team’s overall experience and competence level</li><li>Figure out who will work on what - taking into account the actual tech. Solutions they discussed - and how much time (*) it will most likely take them and put that against known resource availability during the iteration’s time, including planned personnel absences, national holidays, etc.</li><li>Set aside some buffer resources for recurring things like urgent bug fixes that might creep in during the iteration - based upon experience gained on previous iterations of the project or on previous projects altogether</li><li>Set aside some “risk buffer” for things like unexpected absences such as sick leaves, etc.</li></ol><p><em>(*) When estimating effort think in ranges and not single numbers and if you are interested in why that should be so, refer to the excellent book “</em><a href="https://www.amazon.com/Software-Estimation-Demystifying-Developer-Practices/dp/0735605351"><em>Software Estimation: Demystifying the Black Art</em></a><em>” for an in-depth explanation</em></p><p>Or said another way - they need to do *proper* estimation and planning for the iteration. Consequently, If that planning process determines that some part of the “asked-for” iteration goal can not be realistically committed to, then that should be communicated to the PO right away and then the PO will scale down the goal until it is at the same time one that delivers value and is within what the team can realistically commit to.</p><p>The team can do all the above either by themselves or have a facilitator who will help them - but the process should be as described above or the team‘s commitment will most likely not carry any real weight. And that whole process is admittedly somewhat “waterfall-y”.</p><p>But “waterfall doesn&#39;t work, that’s exactly why we invented and need agile methodologies!!” I hear you scream, and you are right - waterfall indeed does not work for multi-month-long software development projects where the market requirements typically change during their implementation phase — or in other words when the time-to-market for the project is long enough that the same market might change by the time the product is finished.</p><p>The point I’m trying to make here is that your standard two-week (or four-week) iteration just does not meet that criteria. The market won’t change in two weeks and you can certainly reliably plan for that short of the interval. So put another way, the <strong>waterfall does not work FOR LARGE SOFTWARE PROJECTS</strong>, but it <strong>DOES WORK</strong> for:</p><p>a) Quite a few other kinds of engineering projects (think bridges, the Apollo space program, the Space shuttle, any building you see around you, etc.)</p><p>b) Short-time software projects (especially if the team has some authority on the level of detail they need to implement — and in Scrum that condition is — or at least should be — met).</p><p>That is also why I don’t really believe that iterations longer than 4 weeks make much sense (I use 2 weeks almost exclusively when I do get a say in it)</p><p>The part of the generic software development process the planning session covers is: <strong>“How should that piece of software be implemented from the tech standpoint?”</strong></p><h4>Frequency:</h4><p>You need to have those once per iteration - at its beginning and before any of the implementation work begins.</p><p>Also, trust me on this one - daily standups will make much much more sense and yield much more valuable information when the planning is done like proposed above.</p><h3>Iteration (Sprint) review/demo session</h3><h4>Input:</h4><ol><li>Team’s commitment (arrived at the planning session for that iteration)</li><li>The team’s true (material) iteration output</li></ol><h4>Output:</h4><ol><li>Verification/Confirmation of alignment between the team’s commitment and delivered iteration output</li><li>Actionable feedback from the business stakeholders on the quality of the delivered increment itself and its alignment with the overall project goals and direction</li><li>The “closure” for the iteration the team gets by seeing the result of their effort and the impact it has on the other stakeholders</li></ol><h3>Purpose and the implementation</h3><p>This one is straightforward, it’s a standard demo session and there is not much to say about it besides the following.</p><p>Everything demoed should be evaluated against PBIs that were taken into the sprint backlog by the team (a.k.a. “The commitment”), which means that the process should be such that each story and all of its acceptance criteria must be demoed and unambiguously determined by the project stakeholders to be either done or not done (there is no “partially done” here).</p><p>That is why your stories (goal statements) and especially acceptance criteria MUST be written well - as those are the ONLY criteria that you can hold the team responsible for - in other words, when all ACCs are satisfied and the stated goal can be demoed to be achievable then the Product owner CAN NOT reject the PBI, the PBI is considered done, and the team did their work and should be commended for it.</p><p>If the PO had a different idea in their head of what they expected, that is a learning experience to write better and more comprehensive stories and ACCs for the next iteration (*).</p><p><em>(*) Or they can throw a Business Analyst/Functional designer/Technical Product owner/whatever you choose to call that person or role in the mix - and have a professional take care of it ;)</em></p><p>The part of the engineering process the demo session covers is <strong>“Does my piece of software really work as expected?”</strong> (**)</p><p><em>(**) in the external context that is, that same question also has to be addressed during the implementation of the iteration’s scope, as there is no worse thing to happen during the demo session than to figure out that the team overlooked or ignored some clearly defined acceptance criteria, or that the system breaks or is unstable</em></p><h4>Frequency:</h4><p>This one is simple — you should have one, at the end of each iteration, marking the end of it. Also, note that you should have those regardless of whether the business stakeholders are able (or want to) to attend or not — although the results tend to be better if they do — at least every couple of iterations.</p><h3>Summary and the conclusion</h3><p>I’d like to end by clarifying the following point, as said before, Scrum is a framework, and there can be (and there are) many implementations of that framework, some of which work IRL and more that don’t. What I’ve presented here is “my” interpretation/implementation (*) that I know works in practice — at least for me and it’s therefore not meant to be understood as the “the only right way” or as “one implementation to end all implementations”</p><p><em>(*) I’m not as presumption as to suggest that I’ve invented anything here — it’s just a way for me to distinguish this implementation from a bunch of others</em></p><p>I’ve been privy to witnessing a whole lot of “by the book” implementations done by experienced scrum coaches and product owners - that failed consistently and reliably, mostly due to the lack of understanding of and consequently either skipping or unconsciously simplifying the principles that I’ve laid out in this text.</p><p>So there you have it, I love scrum and iterative delivery processes in general, and I honestly believe that for most scenarios they are the best approach to designing, implementing, and delivering software products reliably, flexibly, and with minimum risk.</p><p>The only additional thing that I haven’t discussed here is the addition of two non-standard Scrum roles which I use to ensure that all that I’ve described in this text is facilitated and performed optimally and by appropriate domain experts — but that will be the topic for the <a href="https://medium.com/@vedran.krizek/implementing-the-scrum-framework-as-a-robust-software-engineering-process-the-recipe-c443e8abe56a">upcoming article</a>.</p><p>If you are intrigued and you’d like to try this yourself, I’d appreciate it if you give me some feedback on how it went, and what parts of it were natural/easy for you and with which you’ve struggled. I might be able to help you with pain points, and it will help me to refine and improve my approach further.</p><p>Finally, If you need any help with implementing something like this in your organization — you can reach out to me on <a href="https://www.linkedin.com/in/vedrankrizek/">LinkedIn</a>.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=4b5512b1c2cc" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[How can the Scrum framework be effectively implemented for software development? (part 1/2)]]></title>
            <link>https://medium.com/@vedran.krizek/how-can-the-scrum-framework-be-effectively-implemented-for-software-development-part-1-2-9e013d497507?source=rss-7049746239c7------2</link>
            <guid isPermaLink="false">https://medium.com/p/9e013d497507</guid>
            <category><![CDATA[project-management]]></category>
            <category><![CDATA[software-development]]></category>
            <category><![CDATA[scrum]]></category>
            <category><![CDATA[agile]]></category>
            <category><![CDATA[software-engineering]]></category>
            <dc:creator><![CDATA[Vedran "Brko" Krizek]]></dc:creator>
            <pubDate>Mon, 07 Oct 2024 11:12:59 GMT</pubDate>
            <atom:updated>2025-03-25T17:09:46.531Z</atom:updated>
            <cc:license>https://creativecommons.org/licenses/by-nc/4.0/</cc:license>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*xYscqStHCc4T77gxAakliQ.jpeg" /></figure><h3>How can the Scrum framework for software development be effectively implemented? (part 1/2)</h3><h4>There are no two ways about it, Scrum has developed a bad reputation and is often used as an example of something that sounds good in principle and what everyone wants to do, but in the “real world” it just does not “cut it”. The group that particularly looks down on its effectiveness are the developers (and the product sponsors who often essentially burn their budget on unreliable and ineffective delivery) — and they are right. Still, the fault is not in the framework itself, which is exactly what this article is about.</h4><h3>Introduction</h3><p>We’ll start with a bit of context-providing history. Scrum was created in the early 1990s by Ken Schwaber and Jeff Sutherland — both experienced software engineers, consultants, and project managers. The Agile Manifesto was conceived and written in 2001 in a ski resort in Utah by 17 people (including Schwaber and Sutherland) all of whom were very experienced software engineers and consultants (and presumably skiers). We’re talking about people such as Kent Beck, Ward Cunningham, Martin Fowler, Uncle Bob, etc.</p><p>If you don’t know those names, google them, as they come as close to a celebrity level as there ever was such a thing in the software engineering world.</p><p>You got the picture.</p><blockquote>The Scrum framework and the Agile manifesto were created by <strong>software engineers</strong> and the top-level ones at that.</blockquote><p>They were trying to solve a real engineering problem that they experienced firsthand — and that was that large waterfall projects were often impractical and were regularly failing to produce good results in an environment that is changing so rapidly as the market for s software products typically does.</p><p>So they identified parts of the waterfall approach to software development (primarily in the areas of scoping, design, requirements, and delivery) that didn’t work in the “real world” and aimed to fix them.</p><p>However, the part that they didn’t set to change (because it was clear and internal to them) was the foundation of how the software is engineered and delivered in a general sense, regardless of the methodology or framework you end up using.</p><p>What I’ll argue here is that this is exactly the part that was “lost in translation” and when the Scrum framework is being implemented nowadays, that is the root cause of all the typical issues and poor delivery I (and most likely you as well) have observed in numerous Scrum projects.</p><p>It also gives us a clue as to why the developers are the group that seems to dislike it the most. And why they are usually right.</p><blockquote>Effective implementation of Scrum framework presupose a good understanding of how the software is built from the engineering perspective.</blockquote><p>Ok, so what am I talking about here? What are those core elements of the software development/engineering process?</p><p>The idea of Scrum (and agile methodologies in general) is to design, develop, and <strong>deliver</strong> the project scope in manageable, incremental “chunks” that each has a value that can be demonstrated to the non-tech stakeholders clearly and unambiguously. For example, if you need to <strong>explain</strong> how things work rather than being able to “simply” <strong>show</strong> how they work — you are not doing your functional partitioning right.</p><p>This is in contrast with the waterfall approach where all or most of the design is done upfront, and then implemented and delivered in one huge, risky, “big-bang” event.</p><p>The key here is that each of those incremental “chunks” should be a fully realized piece of software which means however small a particular piece is, its conceptualization, implementation, and delivery need to go through all the core steps of the software engineering process or otherwise you’ll run a high risk of ending up with a bunch of code and very little value to show for it.</p><p>So what are those core engineering steps that we need to take into account for each of our product increments?</p><h3>The minimal engineering steps of any software development process</h3><p>I’ll start by pointing out that this section is not an in-depth discussion of details of software engineering and is not intended to turn you into a software engineer (if you want that — the best place to start is by reading the books written by people I’ve mentioned earlier, as those are the canonical works in this field).</p><p>As a consequence, the explanations below are significant simplifications of the real-world process, written in the form of the most basic questions that you need to be able to answer if you’re to build a working piece of software. Nevertheless, I’d argue that they contain all the “important bits” — or at least those bits important for the context of our discussion.</p><p>With that out of the way, let’s begin.</p><h3>What does this particular piece of software need to accomplish? (ie. “what is its function?”)</h3><p>This is the “dreaded” requirements part which often gets shunned in Scrum or any other Agile context because of an unfortunate misunderstanding of the Agile manifesto which states it values communication and collaboration over written documentation — which is completely fine, but it is often read as “all forms of documentations are bad and should be avoided” which is unfortunately horribly wrong (and also contradictory with the fact that scrum does use documentation in the form of user stories and acceptance criteria and the notion that the PBIs should be single source of truth).</p><p>The problem lies in the fact that people often understand documentation only in the form of heaps of formal documents which are hard to follow, and are very complex and immutable regardless of how well they apply to the circumstances that will be valid during the implementation phase of the project.</p><p>That understanding is completely wrong. The only qualification that needs to be met in order for something to be called “documented” requirements is that it conveys the following information:</p><ol><li>Which (demonstrable) goal(s) for which stakeholder this software segment needs to accomplish? (or “What does this particular entity must be able to accomplish by interacting with this particular piece of software?”)</li><li>Which specifics of HOW that goal should be accomplished that do we care about?</li></ol><p>That is about it — this is true for the 100+ page SRS document — which will go into extreme details for point 2 leaving very little (or nothing) to the imagination and discretion of the implementation team, or a minimal backlog item with a story (point 1) and a few ACCs (point 2) that just outline the “important bits” and leave everything else to the team’s discretion and expertise.</p><p>Or put another way:</p><blockquote>“In order to develop any functional piece of software, you need some form of requirements defining what that piece of software should accomplish, in a form that allows the implementation team to independently and with certainty test and demo the result of their work”</blockquote><p>Please note that if the requirements are incomplete or inconsistent — then the gaps will be filled by the implementation team (as they otherwise wouldn’t know what to develop) and that process will be extremely dependent on the individuals filling the gap and their natural biases, abilities and inclinations.</p><p>You’ll be throwing the dice essentially.</p><blockquote><strong>“Without requirements or design, programming is the art of adding bugs to an empty text file.”</strong></blockquote><p>— <strong>Louis Srygley</strong></p><h3>How should that piece of software be implemented from the tech standpoint — so it accomplishes its designed function optimally?</h3><p>That is what’s referred to as the “architecture” or the “technical solution.” Once you know what you need to implement, the next question is obviously — what is the best way to implement it, taking into account all known requirements — both functional and non-functional (for example performance requirements, hardware requirements, etc.)?</p><p>This is what software engineers do, and why most of them became software engineers in the first place (or at least that is true in my case)— finding technical solutions for functional problems. This part includes finding answers to questions such as “Which technologies/programming languages/frameworks will we use for this?”, “What is the optimal system architecture, all things considered”, “How do our internal tech standards apply to this?”, etc.</p><p>At least some of this process is done up-front, prior to any implementation effort — usually as a part of the effort estimation process (you cannot estimate the effort needed to build something if you don’t have the slightest idea how you’d build it), but it also needs to be at least thought about for every implementation iteration — usually during its planning phase. In other words, architecture/tech solution design typically has both some up-front part and can then be done iteratively afterward.</p><p>How much architecture/technical design you need to do up-front, and how detailed it should be depends highly on the composition of your team — the less experienced the individual team members (and the team as a group) are, the more up-front design you need, as, the same as with the requirements, any gaps and inconsistencies will be filled out “just-in-time” by the individual team members, in accordance with their abilities and inclinations.</p><p>Or, put another way, you’ll be throwing the dice here as well.</p><h3>Does my piece of software really work as expected?</h3><p>Once the implementation work is completed, there is one more question that needs to be answered, and that is — are we really done? (and a spin-off of that is “Did we break anything in the process?”) And this is done by testing.</p><p>There are a number of ways you can do testing — and what testing needs to establish and confirm is:</p><ol><li>Does the software achieve what was required of it — both functionally and non-functionally? (you obviously need some documented requirements for that — typically ACCs are the key information here)</li><li>Does the software conform to the expected/agreed-upon technical quality levels? (that is where internal tech standards are useful — and needed really)</li><li>Is the system as a whole still functioning properly with the “new bit” added to it?</li></ol><p>You can do it manually (please don’t), you can write automated tests (please do — at least the functional or integration ones) and you can automate the entire processes by setting up something like a CI/CD pipeline, etc.</p><p>That part of the testing is/should be done by engineers (first) and can be additionally verified by the internal QA (don’t try the approach where QA is the only one testing for completeness/compliance with requirements, QA should test for quality — as its name implies).</p><p>However, for something to be deemed truly complete, there has to be an acceptance/feedback event by the “business” (a.k.a. stakeholders). The role of that particular testing/demoing is twofold.</p><ol><li>It ensures that the interpretation of the requirements is the same by the implementation team and the business (if it is not — then you almost certainly need to up your requirements writing game).</li><li>It provides valuable feedback that can allow the entire development team — from the Functional/Business analysts, and project managers to software and QA engineers and DevOps, etc. to fine-tune their approach for any subsequent piece of software they need to develop.</li></ol><h3>Conclusion</h3><p>I hope that I’ve managed to outline what those “immutable/core” parts of the software engineering process are, and which, if omitted in part or whole, will result in a situation where the delivery of any produced piece of software becomes an extremely risky endeavor relying (unnecessarily so) upon luck and individual team members initiative and talent.</p><p>As I put it before, you’ll be (mostly) rolling the dice.</p><p>So with all that out the way, we’re now ready to see how we can “map” the Scrum framework onto this “immutable” foundation of software engineering and end up with a great, agile software development process that can deliver in a controlled and reliable fashion.</p><p>Or, how to implement Scrum correctly for the software development scenario.</p><p>We’ll do that in <a href="https://medium.com/undabot/how-can-the-scrum-framework-be-effectively-implemented-as-a-software-engineering-process-4b5512b1c2cc">part 2 of this article</a>.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=9e013d497507" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[AI prompts are just requirements written for a robot’s eyes]]></title>
            <link>https://medium.com/@vedran.krizek/ai-prompts-are-just-requirements-written-for-a-robots-eyes-9fdbfdb6090e?source=rss-7049746239c7------2</link>
            <guid isPermaLink="false">https://medium.com/p/9fdbfdb6090e</guid>
            <category><![CDATA[functional-design]]></category>
            <category><![CDATA[prompt-engineering]]></category>
            <category><![CDATA[requirements-engineering]]></category>
            <category><![CDATA[business-analyst]]></category>
            <category><![CDATA[ai]]></category>
            <dc:creator><![CDATA[Vedran "Brko" Krizek]]></dc:creator>
            <pubDate>Fri, 15 Sep 2023 11:31:19 GMT</pubDate>
            <atom:updated>2023-09-17T12:24:33.938Z</atom:updated>
            <cc:license>http://creativecommons.org/licenses/by/4.0/</cc:license>
            <content:encoded><![CDATA[<h4>When you think about it, prompts in the context of generative AI models such as GPT-3, Dall-E 2, Midjourney, etc. are nothing more than a set of requirements written for an AI “implementation agent” — rather than for your garden variety human one.</h4><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*ooFq02WBeMr140vsHsoPLw.png" /><figcaption>A cartoon robot is cooking while reading a cookbook, digital art. Midjourney V5</figcaption></figure><p>The title might seem somewhat oversimplistic (and clickbait-y), but if we examine what the prompts truly are, we can probably agree that the following definition is not a bad approximation:</p><blockquote>A precise set of expectations and instructions written for an AI “implementation agent” with the ultimate goal of them being interpreted by said agent and turned into a tangible artifact that matches those expectations as closely as possible”</blockquote><p>Said artifact can be a piece of software, an essay, an image, a 3D printed object, or anything else the particular “implementation agent” can produce.</p><p>What I’m arguing here is that that particular definition holds true for any requirements you might write as a business analyst, functional designer, or requirements engineer/architect — if we simply replace “AI implementation agent” with “development/implementation team”.</p><p>If I’m correct about it however, then the requirements and prompts for generative AI models are really cut from the same cloth and it stands to reason that many (or indeed most) good practices for writing requirements should apply to this newly conceived craft of writing good AI model prompts, called “prompt engineering” and vice versa.</p><p>That last assertion is actually somewhat testable, so let’s investigate this a bit further</p><h4>What are the good practices for writing prompts?</h4><p>As with anything else, you can write prompts/requirements poorly and you can write them well. The funny thing is that (unless you are truly bad at it) to a layman they will still most likely look good enough in both cases, and they won’t be able to tell a difference.</p><p>Those charged with implementing those requirements, however, certainly will.</p><p>That is the primary reason for the peculiar effect you might have observed yourself — which is that most of the issues in any project tend to manifest themselves in the development phase of the project and not sooner. The reason for that is that the implementation is the first time that any preparation work and the requirements resulting from it are truly put to the test.</p><p>In order to prevent that as much as possible, there are numerous good practices that we can follow when we write our requirements. The exact same is true for writing prompts, and the craft is called “prompt engineering” — and is (somewhat expectedly) rather similar to the craft of requirements engineering.</p><p>To figure out what are the good practices for writing prompts for AI models, we’ll consult the following guides as a reference:</p><p><a href="https://www.promptingguide.ai/">https://www.promptingguide.ai/</a> (The bias here is prompt engineering for LLMs but all the principles apply to prompting any generative AI model)</p><p><a href="https://help.openai.com/en/articles/6654000-best-practices-for-prompt-engineering-with-openai-api">https://help.openai.com/en/articles/6654000-best-practices-for-prompt-engineering-with-openai-api</a> (the bias is the same as the previous reference)</p><p>So let&#39;s check out those resources and see how the practices listed within them apply to requirements writing in general.</p><p>It’s important to note that we will not go over each and every one of the tips and good practices listed in our reference material — as that would make a *very* long and rather redundant article. We’ll instead try to group them into important general concepts and then discuss those instead.</p><h4>Concept #1: Be specific / avoid impreciseness</h4><p>This is the golden rule of writing any requirement in my opinion. There is no place for being vague when you define what you expect the system to do for you. Although that seems like self-evident common knowledge — it’s very very easy to get wrong. Just ask any developer who had to work off of imprecise or unspecific requirements.</p><p>There are two main reasons that the requirements and prompts need to be specific and precise.</p><p>The first is that once any piece of requirements gets to the point of actually being implemented — anything missing from it, any impreciseness, ambiguity, and vague definition WILL be interpreted and filled out with the assumptions by the implementation agent, be it a human or otherwise. You won’t typically be there at that point and the bigger the assumption the team needs to make in order to progress the more likely is for them to guess it wrong and endanger the project as a result.</p><p>And before you say “I don’t need to write my requirements in a way they are very specific and precise because I am an agile product owner and we discuss those things on refinement sessions and the team asks for clarifications when they get to a particular story because we have a great communication and all” — let me point out that you ARE STILL providing all the specifics and precise details — only you do it “just-in-time” instead of upfront.</p><p>The second reason is that you want to be able to determine without a doubt whether the implemented system is truly aligned with the requirements important to the project stakeholders— the more precise the requirements are, the easier that task is.</p><p>As an example: Consider the following requirement “The load time of the homepage is significantly reduced”. This is very vague — if the load times were 5 secs before, and now they are 2.5 secs, that’s certainly a significant reduction but both those load times suck big time. You might try “The homepage loads quickly” — that is a bit better, but it doesn’t cut it either, because everyone has a different notion of what “loads quickly” means. What you need to do instead is state something along the lines of “The TTFB for the homepage is less than 150 milliseconds under no load, and no longer than 300 milliseconds under the load of 100 concurrent requests”.</p><p>If you think “I’m not that technical, I cannot know these numbers”, see concept #4 below — know your domain.</p><p>The preciseness/specificness works the same for AI models as well — here are some examples of precise/specific prompts as stated in <a href="https://promptingguide.ai/">promptingguide.ai</a></p><blockquote>Extract the name of places in the following text. <br>Desired format:<br>Place: &lt;comma_separated_list_of_company_names&gt;<br>Input: “Although these developments are encouraging to researchers, much is still a mystery. “We often have a black box between the brain and the effect we see in the periphery,” says Henrique Veiga-Fernandes, a neuroimmunologist at the Champalimaud Centre for the Unknown in Lisbon. “If we want to use it in the therapeutic context, we actually need to understand the mechanism.””</blockquote><p>Also, see if you can see the difference in their inherent preciseness between these two prompts:</p><blockquote>Explain the concept of prompt engineering. Keep the explanation short, only a few sentences, and don’t be too descriptive.</blockquote><p>vs</p><blockquote>Use 2–3 sentences to explain the concept of prompt engineering to a high school student.</blockquote><p>Note that the latter is much more precise and makes interpreting “what the author really wants” significantly easier than the former, besides the fact it’s shorter.</p><h4>Concept #2: Illustrate what you mean using a carefully selected set of examples</h4><p>If the picture is worth a thousand words, then a good example is worth a thousand lines of requirements. This is not an exaggeration. There is an excellent book on the subject called Specification by Example, and I recommend it wholeheartedly.</p><p>What examples provide the reader with — is the context, and that is extremely important because however well and tight your requirements might be written, they will NOT be “water-tight”, there will still be some residual ambiguities, and imperfect sentence constructions — ie. residues of the fact that requirements writers tend to be mostly human. (And no, generative AI models will not change that just yet).</p><p>As we stated previously, for any ambiguity or “hole” — once you get to the implementation, that hole will invariably be filled with a set of assumptions by the implementation agent/team, and it’s a simple fact of life that — the more context the person (or AI model/robot) has, the better their assumptions will be. Or put otherwise, their assumptions will be that much more in line with what you tried to convey through your requirements, the more of the context that those requirements “live in” is provided to them.</p><p>And examples are probably the best way to provide a lot of context with very little content. (Examples have the best ratio of context/content that I know of)</p><p>Writing good examples is not a trivial task, though, and I’d strongly recommend you to read the book I’ve mentioned before. You won’t be sorry.</p><p>When it comes to AI model prompts — there are several techniques such as few-shot prompting, chain-of-thought, and a bunch more listed in our reference materials mentioned before.</p><p>Here is an example of a chain-of-thought technique (see also few-shot-learning) used on an actual prompt (source: <a href="https://promptingguide.ai/">promptingguide.ai</a>) to achieve correct results for a type of query that was for a long time a hard nut to crack for LLMs in general:</p><blockquote>The odd numbers in this group add up to an even number: 4, 8, 9, 15, 12, 2, 1.<br>A: Adding all the odd numbers (9, 15, 1) gives 25. The answer is False.<br>The odd numbers in this group add up to an even number: 17, 10, 19, 4, 8, 12, 24.<br>A: Adding all the odd numbers (17, 19) gives 36. The answer is True.<br>The odd numbers in this group add up to an even number: 16, 11, 14, 4, 8, 13, 24.<br>A: Adding all the odd numbers (11, 13) gives 24. The answer is True.<br>The odd numbers in this group add up to an even number: 17, 9, 10, 12, 13, 4, 2.<br>A: Adding all the odd numbers (17, 9, 13) gives 39. The answer is False.<br>The odd numbers in this group add up to an even number: 15, 32, 5, 13, 82, 7, 1. <br>A:</blockquote><p>Resulting in the following answer:</p><blockquote>Adding all the odd numbers (15, 5, 13, 7, 1) gives 41. The answer is False.</blockquote><h4>Concept #3: Don’t state what NOT TO DO, but rather state what you want DONE INSTEAD</h4><p>Negative or prohibitive requirements or instructions (“don’t use X”, “don’t ask for Y”, etc.) are more common in the world of non-human implementation agents than human ones, mostly owing to the fact that humans are (generally speaking) intelligent and posses a common sense while AI models really aren’t and don’t.</p><p>However, the underlying principle of “don’t state what NOT to do, but rather state what to DO INSTEAD” illustrates the importance of framing the requirements/instructions just right for the particular reader’s eyes.</p><p>The reason is that whenever you don’t explicitly state what YOU WANT to happen, you leave a *lot* of solution space open for interpretation, and implicitly state “Whatever you produce here, I’m fine with it”. That is a VERY dangerous thing to do with AI models because while the humans have common sense at their disposal to help them not to wildly stagger through solution space, AI models typically don’t and will therefore often produce results that are quite “off” from what you’d reasonably expect and could even ignore your explicit instruction not to do something.</p><p>When you however state what you WANT done, you neatly circumvent this problem of leaving too much solution space for the implementation agent with no real intelligence or common sense to make sense of it in a way that the human would.</p><p>That said, this concept applies to standard requirements writing just as well, as it can be seen as a specific aspect of the “be specific/precise” rule/concept — which really boils down to “don’t leave too much of the solution space open for interpretation” which is always a good idea, especially when you write for a team of inexperienced developers.</p><p>An example of such a prompt could be:</p><blockquote>You will be given a movie name and should provide a 3 to 5 sentence description of that movie. In case you are not familiar with the movie, do not produce the description but provide only the following reply “I have never heard about that movie in all of my months of existence so far”. The movie is “fear and loathing in Las Vegas”</blockquote><p>the response would be what we expected:</p><blockquote>“Fear and Loathing in Las Vegas” is a surreal and darkly comedic film directed by Terry Gilliam, based on Hunter S. Thompson’s novel. The movie follows the drug-fueled journey of journalist Raoul Duke (played by Johnny Depp) and his attorney Dr. Gonzo (played by Benicio Del Toro) as they embark on a wild and chaotic road trip to Las Vegas to cover a motorcycle race. Along the way, they encounter bizarre characters, engage in mind-altering drug experiences, and confront the disintegration of the American Dream. The film is known for its eccentric storytelling, hallucinatory visuals, and a scathing commentary on the counterculture of the 1960s and 1970s.</blockquote><p>Now if we try asking for a movie we know doesn’t exist:</p><blockquote>The movie is “Brko’s imaginary movie”</blockquote><p>The response would not be some hallucinated one, but just:</p><blockquote>I have never heard about that movie in all of my months of existence so far</blockquote><p>And just for s**t and giggles, here is the hallucinated reply as well — one that we’d get if we didn’t specify what we don’t want the system to do and what we wanted done instead. This one was done using GPT-3 model directly (via OpenAI playground) as ChatGPT has some hidden prompting going on behind the scenes at the beginning of each conversation thread that prevents it from hallucinating too much</p><blockquote>Brko’s Imaginary Movie” is a mind-bending psychological thriller that explores the blurred lines between reality and imagination. The film follows Brko, a troubled artist who becomes consumed by his own vivid fantasies. As Brko’s imaginary world begins to intertwine with his real life, he struggles to discern what is real and what is mere fabrication of his own mind. As the line between reality and imagination continues to blur, Brko must confront his inner demons and unravel the truth before losing himself completely in his own creation.</blockquote><h4>Concept #4: Understand the domain you’re prompting as much as you can</h4><p>This is not a prompt engineering technique as such — but is an essential concept nonetheless in my opinion.</p><p>The reason that the LLMs and generative AI models won’t replace us all anytime soon is the fact that they still need someone to prompt them, and to prompt them competently when it comes to that. Therefore the same way, as you really need to understand the domain that you’re writing requirements for — the same goes for AI model prompting. The good thing with LLMs though is that you can increase your knowledge of the domain in “baby steps” by focusing your prompts as your domain knowledge increases.</p><p>The analogy that works for me is that of a head chef in a fancy restaurant — that person typically doesn’t dice onions, make a rue, or peel and boil potatoes — regardless of the fact that he or she can certainly do it competently. All that “grunt work” is done by cooks who are skilled at their work and they pretty much provide all components for any fancy meal — but the head Chef is one who combines them, seasons them perfectly, and ultimately elevates the components into the superior end product. Also, it comes as no surprise that the head chefs tend to really understand the domain of cooking and especially what constitutes a meal that would be acknowledged as fancy and high-end by its consumers.</p><p>The point is that it’s rather analogous to how generative AI is used in practice — it (figuratively speaking) replaces the cooks in the analogy above and dices and sautees the figurative onions and boils the figurative potatoes faster than any human could, but it still requires the head Chef to make sense of its output (if we care about quality that is).</p><p>And as, In my opinion at least, the only way to make sense of any output is to understand the nuts and bolts of the domain of that output (and be VERY AWARE of the fact that you’re probably not an expert, but rather someone who understands *just* the nuts and bolts) — and to be able to identify when you need to consult someone who understands the domain better than you.</p><p>The same goes for classic requirements — if you’re designing a mobile application or an embedded system or an API — you *have* to understand how those systems work, what they are composed of, and how they operate “under the hood” — not to the level that you can implement them yourself obviously, but at least to the level that you can confidently explain them to a layperson in a way that makes sense to both you and them</p><h4>So what does it mean for a business analyst or a functional designer such as myself?</h4><p>Let&#39;s consider some tips from the OpenAI help page related to their generative AI models:</p><ul><li><strong>Be specific, descriptive, and as detailed as possible about the desired context, outcome, length, format, style, etc</strong></li><li><strong>Articulate the desired output format through examples</strong></li><li><strong>Reduce “fluffy” and imprecise descriptions</strong></li></ul><p>I dare to say that if I didn’t tell you that they come from the OpenAI help page in advance — you wouldn’t be able to tell them apart from good practices for writing requirements in general.</p><p>Hopefully, everything written so far demonstrated that “classic” requirements and AI prompts have quite a few things in common. We’ve just scratched the surface though, and I strongly encourage you to read the prompt engineering resources listed at the beginning of this article.</p><p>But what does it mean for a functional designer/business analyst/requirements engineer?</p><p>Well, as any non-fiction writer can tell you — you write for your audience. For example, I tend to write requirements differently if they will be implemented by a team with a strong understanding of the domain and its high context than I would for a group of juniors or a team fresh to the project or the domain.</p><p>The same concept applies here — when you are writing prompts you are still writing requirements it’s just that your audience is non-human.</p><p>The consequence, in my opinion, is that:</p><blockquote>Those who can write requirements well (requirements engineers, functional designers, and business analysts), and “tailor” them for the project context and intended audience, are extremely well-positioned to become decent prompt engineers quickly</blockquote><p>The reason for that is, that most of the skills, including pretty much all of the hard-to-learn written communication skills are already there, and only the prompting techniques specific to the AI model in questions should be learned, and those are really not hard — provided you are technically inclined enough — and you should be if you’re designing and documenting requirements for IT systems (see “understand the domain”).</p><h4>Sounds interesting. How should I proceed?</h4><p><a href="https://en.wikipedia.org/wiki/Hunter_S._Thompson">A very smart (and also very crazy) person</a> stated that “paranoia is just another word for ignorance”, and probably the biggest obstacle you are facing when it comes to you getting involved with AIs is the misconception that “that AI thing is cool but it’s also crazy complex and hard to understand unless you have a Ph.D. in math — it’s just too complicated for me”.</p><p>Luckily for you, nothing can be further from the truth. So here is what I’d suggest you to try to do:</p><p><strong>Step 1:</strong></p><p>You should first learn what neural networks are as they are a pretty simple concept really — don’t let the fact that there is math involved scare you off, as you can get a solid grasp of the fundamentals and the general workings of an average neural network with basic high school math (or even less than that).</p><p>Then expand what you’ve just learned by reading up (you can ask ChatGPT to recommend some good “math lite” resources) on what the generative models are and what they add to the basic neural networks concept you’ve just learned about.</p><p>That first step will help you stop being afraid of “AI” and understand that the “I” part of “AI” is a pretty specific and constrained one — not what you might think reading/watching all the pop-science-media headlines and listening to some pundits.</p><p>It will also help you get a grasp of what exactly is that thing that you’re writing requirements (prompts) for — ie. it will get you acquainted with your new audience/readers.</p><p><strong>Step 2:</strong></p><p>The second step should be reading about prompt engineering and comparing those concepts with what you already know about writing requirements (expectations + instructions) in general.</p><p><strong>Step 3:</strong></p><p>And the third step is rather simple — experiment, experiment, and then experiment some more. Play around with actual generative models such as GPT, Dall-E 2, and Midjourney — and any model you can get your hands on really, and try to “feel” how they respond to the things you ask them to produce for you —they each have their strong and weak points — and then try to work around obstacles you encounter by tweaking your prompts by applying some prompt engineering techniques — to get better results.</p><p>And to get you started — here are some resources that you can start with:</p><p><a href="https://www.youtube.com/playlist?list=PLZHQObOWTQDNU6R1_67000Dx_ZCJB-3pi">This one</a> is an excellent, math-free (mostly), and expertly presented introduction to neural networks where the concepts are explained over a very simple and easy-to-understand example.</p><p>And then, if you are not afraid of math — you can go over the <a href="https://www.youtube.com/playlist?list=PLZHQObOWTQDNU6R1_67000Dx_ZCJB-3pi">following videos</a>, which should give you some solid understanding of what we’re talking about when we say “AI” or “neural network”, and to understand that there is no magic involved.</p><h4>Conclusion</h4><p>If you are writing requirements for a living, and you are good at it — learn how to prompt generative AI models competently, and add prompt engineering to your set of skills, It pays well and generative AI models *is* the disruptive, world-altering technological advance we’ve been waiting for so long — and, if you are anything like me and love technology that has a real impact — then it should feel good to be part of that.</p><p>Therefore, do yourself a favor, and don’t miss this opportunity.</p><p>I know, I won’t.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=9fdbfdb6090e" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Solution design first! Part 2 — The functional design]]></title>
            <link>https://medium.com/@vedran.krizek/solution-design-first-part-2-the-functional-design-82f25f2a9b8?source=rss-7049746239c7------2</link>
            <guid isPermaLink="false">https://medium.com/p/82f25f2a9b8</guid>
            <category><![CDATA[product-owner]]></category>
            <category><![CDATA[solution-design]]></category>
            <category><![CDATA[business-analyst]]></category>
            <category><![CDATA[functional-design]]></category>
            <category><![CDATA[ux-design]]></category>
            <dc:creator><![CDATA[Vedran "Brko" Krizek]]></dc:creator>
            <pubDate>Tue, 07 Mar 2023 15:45:24 GMT</pubDate>
            <atom:updated>2023-03-08T14:26:51.293Z</atom:updated>
            <content:encoded><![CDATA[<h3>Solution design first! Part 2 — The functional design</h3><h4>In the previous segment of our story, we talked about solution design in general. In this segment, we’ll dive deeper into one particular part of it — the functional design.</h4><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*gXDNn1m2oEVezDg__TAXfw.png" /><figcaption>“A functional designer solving a jigsaw puzzle on a tabletop, digital art, synth-wave”, OpenAI Dall-E 2, 2022</figcaption></figure><h3>A quick introduction</h3><p>We’ve covered a lot of ground in the <a href="https://blog.undabot.com/solution-design-first-part-one-b012db56866f">previous post about the solution design as a concept</a>, but for the subject of this one, probably the most relevant is the following statement:</p><blockquote>Functional design is a basis and a prerequisite for all other design processes (UX/UI and system architecture design) — as well as for the development process itself</blockquote><p>Put in another way, in a hub and spoke model — functional requirements are the hub (or if you prefer the “Big Lebowski model”, then they are that proverbial rug that ties the room together).</p><p>But, in whichever way we decide to put it if what we’ve stated above is indeed true, then the functional design is *very* important, so let’s try to dive deeper into its concept.</p><h3>The functional design</h3><p>We’ll start with the following definition/claim</p><blockquote>The functional design is a process through which we discover and specify the functional requirements for a solution in a way that ensures that those requirements are optimal for the given problem and are at the same time functionally complete, implementable, and agnostic about the details of their subsequent implementation</blockquote><p>What this implies is that the functional design is (or should) always be the FIRST process that happens in any software solution development scenario (and not only in software development, but that’s really outside the scope of this post)</p><p>It also follows that every other process which is a part of the wider software development process, regardless of whether the process in itself is agile or not, relies heavily on a well-defined description/specification of those functional requirements.</p><p>Functional requirements themselves are, in their essence, the explicit specification of all the GOALS the system should allow its users to achieve — with its ultimate purpose being the base input (or a foundation) for all subsequent design processes. The goal of those design processes would therefore be to define HOW those GOALS should be achieved by the system’s users.</p><blockquote>The functional requirements are a collection of all the GOALS that the system under design should allow for any of its users/actors/stakeholders to ACHIEVE by using it, accompanied by a set of statements that define the important details and acceptance criteria for those goals, written in such a way that no implementation details are implied.</blockquote><p>Another (shorter) way to define the functional design (and its primary actor — the functional designer) would be:</p><blockquote>The role of the functional design (and a functional designer) is to define (and maintain) WHAT the system should do while taking as much care as possible to NOT suggest the details of HOW it should do it (*).</blockquote><p><em>(*) unless at the moment of creating the functional requirements, some implementation details are already known — for example, there will be cases where the functional designer will arrive at the scene only after some (or all) UX/UI design has already been done (that’s not the best approach by any means, but it does often happen for various reasons), in which cases some of the HOWs (the user interface is really an implementation and embodiment of the wanted user experience) are already defined and a good functional designer will then include those details in the functional requirements they produce (see aspect #3 later in this post for more information)</em></p><p>If we consider what we’ve defined so far, the following 3 main aspects of functional design (and the role of the functional designer) stand out:</p><ol><li>Discovery, documentation, and validation of a complete set of functional requirements (a.k.a. WHATs)</li><li>Maintaining the separation between the WHATs and the HOWs (ie. between functional requirements and implementation details)</li><li>Maintaining the role of the functional requirements as a HUB in the hub &amp; spoke model (ie. maintaining the relationships between the WHATs and their subsequently designed HOWs)</li></ol><p>We’ll address each of those in its own chapter.</p><h3>Aspect #1 - The discovery, documentation, and validation of the functional scope</h3><p>This aspect of the functional design is most akin to what a typical business analyst does. Techniques are somewhat similar (and will be explained in more detail in the subsequent post in this series that now seems like it’s going to be at least a “trilogy”) and they “boil” down to the following:</p><ol><li>defining the high-level, complete functional scope — by defining actors and their goals, or user stories via techniques such as actor/stakeholder interviews and user story mapping, etc.</li><li>defining the behaviors and specifics of how the particular goals are reached by writing down use cases, acceptance criteria, business rules, etc.</li><li>making sure that the specified scope is functionally complete — via techniques/approaches such as process/entity input/output mapping, etc. (or even a simple “CRUD” method <a href="https://blog.undabot.com/building-a-functionally-complete-set-of-user-goals-using-the-c-r-u-d-method-7b19bcf3b060">described here</a>)</li><li>making sure that the specified scope is implementable — via reviews by the system architects and UX/UI designers</li></ol><p>One defining element of this part of the process is that the first step defined above requires input from the client for whom we’re designing the system, and that input will never be functionally complete. So as a result, a functional analyst will first DISCOVER the “kernel” that the client can provide us with and then DESIGN the functional scope around it, ensuring that it’s functionally complete, consistent, and implementation agnostic at all times.</p><p>Or, to sum it up</p><blockquote>One of the most important roles of the functional designer is an ability to fill-in the gaps between the client&#39;s idea and the functional scope of a standard IT solution (be it a web application, a native mobile one, an offline server process, etc.) in such a way that the resulting functional scope is complete and consistent</blockquote><p>Since examples are to definitions what pictures are to words, let’s try to illustrate what we mean by this “gap” that the functional designer needs to fill — with an example, and this time, for the reasons of making this text more glamorous than a typical technical text tends to be — instead of a software solution we’ll build a “luxurious floating solution” ie. a yacht as it’s commonly referred as by the layman.</p><h4>And the rest is a yacht</h4><p>Picture the following: You are asked to design and build a yacht for a client, and the client who came to you has a very clear idea of certain things about that yacht, perhaps they have a very detailed set of requirements for a lounge going as far as defining the number of mirror segments in a disco ball and have a clear idea how many people should yacht comfortably house, and exactly which other yacht owner it should make jealous, etc. but for all the rest of the details that define “a standard luxurious floating device” the requirement is simply “the rest should be like a yacht”.</p><p>Ie. those “client sourced” requirements would go something like this</p><ul><li>Should comfortably house 10 people</li><li>There should be 3 bathrooms</li><li>The disco ball in the lounge should have at least 10 000 individual mirrors</li><li>…</li><li>(And the rest should be like it’s on any yacht that I, the client, personally find to be attractive)*</li></ul><p><em>(*) that “and the rest is a yacht” bit is both a silent assumption and also where solution design in general and functional solution design, in particular, come into play.</em></p><p>Now if you change “boat” to “web application” or to “Android app” or to whatever you produce — my proposition here is that the (extreme) example above represents something you’re familiar with, within your line of work.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*M2WUkcJFCCt0vDZ9YNMncg.png" /><figcaption>“A modern and luxurious yacht sailing over the sunny ocean, digital art” Dall-E 2, 2022</figcaption></figure><p>The main difference here between the “mere” discovery process is that the functional solution design is not a passive “interview-based” process where you get and document functional requirements from the client, but rather that you actively provide the first iteration and draft of “and the rest should be a yacht” part of the requirements and only then involve the client to confirm your solutions.</p><p>What you achieve by doing this is that the client fairly quickly</p><ol><li>come to the (guided) revelation that there is much much more to this project scope than they thought</li><li>realize that you got their back</li><li>get to focus on “money-making stuff” rather than minute details of how the Fulltext search will work</li></ol><p>So to sum up, the role of the functional designer is both to discover and document the functional requirements (WHATs) and then to build them up and fill out any functional gaps, until they describe an optimal solution of a type (ie. web application, etc.) that their organization is in the business of building.</p><h3>Aspect #2 — Maintaining the separation between WHATs and HOWs (a.k.a. being implementation agnostic)</h3><p>Perhaps you’ve spotted a “theme” forming in those definitions — and that is that we’re going to lengths to separate the functional design from other design processes and the implementation, as well as to separate WHATs from HOWs. That is not by accident mind you, that particular aspect of the functional design is extremely important for a rather simple reason.</p><p>Think about it. Software development is a collaborative process that invariably involves a team of highly skilled specialists. You have your UX/UI designers, system architects, developers, testers, etc. Also, none of them comes cheap.</p><p>So given that each of those roles brings a lot of expertise to the table, as a project sponsor, or manager, what you want is that all of that expertise gets utilized to its maximum, (or in other words, to get the “most out of your buck”). The most efficient way of doing so in my experience is to make sure that:</p><ol><li>Everyone is able to utilize their expertise to the maximum applicable extent (ie. UX/UI designers are better than anyone else at designing user interfaces and interactions, as are system architects when it comes to defining the optimal technology stack and architecture, etc.)</li><li>Everyone is given well-defined problems (WHATS) and give them as much freedom as possible to come up with solutions (HOWS)</li></ol><p>For example, if a functional designer oversteps their boundaries and starts venturing into UX/UI by for example inventing references to particular UI elements — such as buttons, etc. — in their use cases or acceptance criteria, then the UX/UI designer (who by definition comes to the stage, AFTER the functional designer) can not bring it’s full expertise to the project — as some of their work has already been done (usually poorly or average at best) for them by the functional designer. At that point you usually have one or other of these two outcomes:</p><ol><li>UX/UI designer argues with the functional designer and your team cohesion suffers as a result</li><li>UX/UI designer shrugs and works around the UX/UI details interjected by poor functional design, and as a result, you don’t get the full “bang for your buck” from your valuable UX/UI designer.</li></ol><p>So what logically follows from the argumentation above is that one of the principal skills that the functional designer should possess is to think in purely functional terms and keep their distance from the HOWs as much as possible.</p><p>Here is an example of how that typically can be done in practice:</p><h4>On being UI agnostic — or the UX designer is a functional designer’s best friend</h4><p>UX/UI design and functional design really go hand in hand, or as one of my more eloquent (and acerbic) friends succinctly has put it, “we all fart in the same sleeping bag”.</p><p>However, regardless of how close those two processes get, the UX/UI design does come AFTER the functional design and is based upon it. So it’s very important for the functional designer to keep in mind that they are not UX/UI designers and that they shouldn’t overstep their “jurisdiction”, or they’ll both get UX designers angry for a good reason, and will also jeopardize the overall quality of the product.</p><p>In practical terms, that means that all the output of the functional design process (user stories or actor/goal pairs, acceptance criteria, use cases, and business rules) MUST be UI agnostic.</p><p>For example, consider this main success scenario for a user story stating “As a user, I can place an ad for my bicycle, so that I can have it listed and found by potential buyers”:</p><ol><li>The user clicks on a “submit” an ad button</li><li>The system renders a UI that contains a select box with all available ad categories</li><li>The user selects the “bike” ad category from the list and clicks on the “proceed with ad placement” button</li><li>The system renders a UI that contains the following input elements: A text input for the ad title, A select input element populated with all bike manufacturers, etc…</li><li>…</li></ol><p>Now consider this, UI agnostic use case for the same user story</p><ol><li>The user informs the system that they want to place an ad</li><li>The system asks the user in which category they want to place their ad</li><li>The user informs the system that they want to place an ad in the “bikes” category</li><li>The system asks the user to provide the following information about their ad: ad title, bicycle manufacturer, etc.</li><li>…</li></ol><p>The first use case heavily implies UX (clicking on a button after which a different UI is rendered) and UI (listing individual input elements), while the second focuses on UI-agnostic interaction between the actor and the system. The first will irritate your UX designer colleague and make their job more constrained and less creative, while the second will give them all the required information they need to do their magic and let them design the living daylights of those user stories.</p><p>Also, note how the second one rather clearly implies that every ad has a category as a defining characteristic and that the ad&#39;s structure might differ between categories. That is the desired “side effect” of a decently written UI agnostic use case — that it communicates the crucial information without obfuscating it with UI details.</p><p>It’s very easy to slip into “hidden UI” design while designing the functional requirements, as most of us share the hidden conviction that “I’m not a designer, but I know what I like” (just like everyone wrongly thinks that they are a football coach, national sports team selector, epidemiologist, or generally an expert in any topic that they feel strongly about but haven’t really studied in a non-superficial way), but that is wrong and is a duty of a good functional designer to be aware of it and to take action to avoid it.</p><h3>Aspect #3 - Maintaining the role of the functional requirements as a hub in the hub &amp; spoke model</h3><p>Any project will go through the solution design phase (voluntarily or implicitly/silently) and since the solution design is composed of three separate but highly interconnected design efforts (functional, UX/UI, and technical/architecture) performed by a separate group of specialists, what often happens (If we don’t take actions to prevent it) is the “balkanization” of the requirements as a whole, and loss o hub and spoke relationship between them and also, loss of the single source of truth principles.</p><p>On many projects I’ve been involved with, most of those which had some degree of issues with failing to reach their sprint goals, missing the deadlines, or have suffered an abundance of “but we thought that…” situations, the general context was often that the functional requirements were out of sync with the UX/UI designs/templates. The problem was that the technical/development requirements were based mostly on those UX/UI designs, resulting in the incorrect or incomplete implementation of required underlying behaviors.</p><p>That is not a good situation to be in, but unfortunately, it’s very common unless there is someone whose role is to “own” the functional requirements and ensure their role as a hub for all other requirements remains stable throughout all project phases.</p><p>Scrum methodology has this covered by having a product backlog owned by the product owner — and that backlog is composed of story cards where each story card must be considered a “single source of truth” about the particular story and therefore must contain the functional requirements (the story and implementation agnostic/function acceptance criteria) and all other requirements must be referenced within it.</p><p>The fact that this is often not observed in the actual implementation of the scrum is a topic for another post, but still, the framework is solid and the role of the functional designer in that context is to mimic that of the ideal product owner in the scrum framework and ensure the integrity of the product backlog (or it’s equivalent) regardless of the project methodology.</p><p>This goal is typically achieved by the functional designer being the “owner” of the requirements (regardless of what form they are in) and making sure that the team understands the three “pillars” of the solution design process.</p><blockquote>A functional designer is the OWNER (and sometimes the defender) of the functional requirements throughout the entire development process.</blockquote><p>Open and unhindered/informal communication regarding the requirements — ie. that everyone involved is aware that the requirements might and will change, and that it’s ok, provided that the “referential integrity” of the whole functional scope remains undamaged, is of crucial value and should be one of the main methods through which the goal of maintaining the hub and spoke model is achieved.</p><h3>The hidden role of the functional designer (a.k.a. business analyst) — a “solver of problems”</h3><p>In most situations, a functional designer will be the first person that the client will have an operational experience with. Up to that point, the client was typically involved only with salespeople, account managers, and perhaps project managers — but everything done was related to setting up the project and discussing budgeting, and the “first day of the project” is usually lived by the “point person” from the client side and the functional designer alone.</p><p>At that point, that “point person” will feel quite a bit vulnerable and unsure — since they know that”</p><ol><li>A lot of IT projects fail for one reason or another</li><li>The eventual failure of “their” IT project *will* reflect on their immediate career path</li><li>They are not able to create a solution by themselves so they are relying on the “kindness of strangers” (a.k.a. you) to do it for them, and to do it well.</li></ol><p>So what they really need (and hope for) from their functional solution designer, is not just to be technically competent and to be able to design great functional solutions, but to first and foremost be this guy:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/498/1*civS3jpWgG0KSxYsD6xpWw.gif" /><figcaption>Harvey Keitel as Winston Wolf in Pulp Fiction (1994).</figcaption></figure><p>The ability to solve problems on the spot, mold the functional scope, and navigate the solution space “in real-time”, in general, are key skills any functional designer should possess, but they are far from the only ones — <a href="https://blog.undabot.com/so-youd-like-to-be-a-requirements-architect-eh-db4370f110e3">here is a link to the blog post</a> that discusses other required skills in more detail, just replace the term “requirements architect” with “functional solution designer” and you’re golden.</p><h3>Summary</h3><p>In this post, we’ve talked about quite a few things and hopefully defined what functional design is, why it’s essential, and what are its main aspects/components. We also touched on its deliverables and the “hidden” role of the functional designer.</p><p>In the next post in this series, we’ll perform an actual functional design of a simple but realistic system, and hopefully, provide you with that proverbial rug that ties all we’ve talked about so far together.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=82f25f2a9b8" width="1" height="1" alt="">]]></content:encoded>
        </item>
    </channel>
</rss>