6 Minute Read
The classic Swiss Army Knife (SAK) is an admired novelty with popularity that transcends generations of doers. The image of the trinket splayed on a tree stump evokes Tim Allen grunts and imaginative delusions of conquering nature with Bear Grylls abilities. Even if this doesn’t apply to everyone who reads this, for reasons relevant to the economy of complexity, or the economy of tight budgets, here’s a thesis: having the ability to do more with one tool is desirable. This begs the question — is it better to take the bait and choose a tool that is adequate for many purposes, or is it better to choose tools that excel at fewer purposes? The answer, of course, is that it depends.
Tools for Tool Builders
DevOps tools are used by software development teams to help manage the process of building, deploying, and supporting complex, custom software. Tools in this genre that have had the greatest commercial success are typically those that have taken a SAK approach, boasting a diverse feature set that includes Agile planning, code repository linking, Quality Assurance (QA) tracking, build pipelines, and support for additional third-party add-ons. Some of the most popular tools on the market include:
- Jira (Atlassian)
- Azure DevOps (Microsoft)
- Sprints (Zoho)
With this post, I’d like to call attention to a decision many teams make- that is, to draw the line at having one DevOps tool with basic Agile planning features for managing the requirements backlog and writing code, and foregoing incorporation of tools with richer content management capabilities. The net result is one very powerful tool (arrrawr!), alongside tradeoffs that manifest as degraded requirements documentation outcomes (ouegh?).
Agile Planning is not Enough
We first shape our tools, and thereafter our tools shape us. -Christoph Magnussen, CEO of Blackboat
The preceding quote is difficult to attribute to its original author, so I’m citing the source I heard it from first. Christoph is an outstanding content creator, and I came across his company Blackboat early in my consulting days. They stood out to me as a relatively small agency with equal parts creative and technology consulting chops. When Jen came onboard while R. Maestas was a very young company, I envisaged modeling ourselves after Blackboat should we ever decide to grow our hybrid design/tech/management consulting company. This quote is a refrain featured often in Christoph’s content. I think it perfectly illustrates the point that developers, as both the creators and users of DevOps tools, have shaped these tools into something specialized for their needs. A fundamental observation, that isn’t always stated this plainly, is that the Agile planning features in developer-oriented DevOps tools excel within the scope of Agile planning for the software developers. Furthermore, the scope of Agile planning activities does not include managing a Requirements Backlog. As an analogy, professional sports teams have personnel whose jobs revolve around a single output: written playbooks. Similar to activities around managing requirements backlogs, heaps of data get analyzed using special skills and platforms in order to come up with optimized playbooks. Even though many members of a sports team never touch a ball (and many who work on software projects never write a line of code), their efforts can have extraordinary impact on game outcomes. From my experience as a team member and leader of various software projects, I consider the development teams’ Agile development activities- writing the code and participating in ceremonies like grooming, pointing, and sprint planning to be innately separate from the requirements gathering and requirements backlog management activities that involve Product Owners (PO), Business Analysts (BA), and Subject Matter Experts (SME). IT departments will sometimes turn these symbiotic teams loose with a SAK DevOps tool, and because the teams’ purposes, needs, and specializations are so different, both teams wind up struggling. Anecdotally, the participants (mainly BAs) and the deliverables involved in activities related to building a Requirements Backlog are fundamentally different from those involved in managing development sprints, reviewing pull requests, conducting quality assurance activities, and writing code. Professional athletes run drills, play in scrimmages, and rapidly interpret concepts from X’s and O’s on a whiteboard. Their support personnel in the back office would be ineffective with these same techniques in the different, but still competitive world of data analytics. In a similar fashion, developers take cues from their Agile planning tools in order to write code within their own Integrated Development Environment (IDE). Developers don’t write code not the Agile planning tool, and accordingly POs, BAs, and SMEs should have a dedicated platform for their requirements backlog.
The Team
Executive Leadership | Strategic Direction | ||||
Product Owner | Product Roadmap | ||||
Business Analysts | Requirements | ||||
Developers | Software | ||||
End Users, SME’s | Business Value |
POs have a leading role on software projects. They take executive or other high-level direction to establish the product roadmap. Product roadmaps are a collection of items that document, in business terms, the full capabilities a software product is expected to have. Iterations of the product roadmap document are fed back to executives, who can freely use the document to affirm their high-level understanding of what the product will do and to provide direction and input on refinements to this “big picture” plan. A PO’s roadmap is essential for the ultimate achievement of a highly successful software product, but each roadmap item requires detailed elaboration. This elaboration, refinement, and repackaging of roadmap items are all responsibilities of BAs. Business Analysts use the roadmap document as an input to their own activities including planning project phases, milestones, epics, features, and eventually eliciting detailed requirements from Subject Matter Experts. Technical details are not yet present in the roadmap or requirements documents, but at this point, we’ve set the stage for better outcomes from our valuable developers’ efforts. To perform at their best, developers need to work in an environment that includes the following: developers need clearly communicated requirements, and they need a workspace to manage technical details down to actual lines of code.
Are we there yet? Signs to recognize when development work is ready to begin
Roadmap items resemble clearly communicated requirements, but if they have been sufficiently generalized for a business executive (i.e. their intended audience), then they are inadequately descriptive for the needs of a developer. For example, describing a feature like “print the current day’s order picklists” is succinct and meaningful to an executive, but implementing this capability might require extensive development effort that could span several sprints. The product may need new features including logic to determine the current local day (as opposed to the HQ’s or the UTC current day), it may need to perform operations to securely request order data from a third party, and after receiving the raw data it may need to perform manipulation in order to get it into a JSON document that is sent to yet another system to generate a human-readable PDF of the picklists. As projects with this degree of complexity begin to take form, it is important that high-level features be broken down into bite-size chunks. If the discussions, debates and decisions about how requirements are broken down happen in the DevOps/Agile Planning tool, this results in distracting noise in what should otherwise be a clean, tailored representation of a backlog of ready-to-develop work packages. The objective of maintaining a curated backlog of developer ready work should be having an adequate amount of sufficiently small work packages so as to make it possible to do all of the following with one of these packages in a single sprint:
Action | Notes |
1. Understand the requirement | It is the responsibility of the BA to act as the channel that SME’s communicate their needs through, and refine this into work package (i.e. User Story) sized chunks of work.
Teams can refine requirements in meetings (synchronously), or by using modern collaboration and content management platforms (asynchronously).
Asynchronous collaboration, like having threaded conversations in instant messaging tools or @ mentioning team members inline in CMS documents, is preferable in most cases. Thoughts shared during synchronous conversations are ephemeral. The CMS can be leveraged to document team feedback, and even developers’ notes for future reference when the code is actually being written.
Periodic meetings, like grooming sessions, provide opportunities to review user story drafts in the CMS before they are eligible to add to future sprints. This is a double-edged approach, that has the benefit of team engagement, but the in-person setting can disproportionately amplify the voice of extroverted team members and seem like a waste of time for non-contributing team members. Managers should consider incorporation of asynchronous collaboration approaches to make these meetings more effective.
If the team collectively decides a requirement is too large or poorly defined to accomplish in a single sprint, the BA should break the work down further. |
2. Write the code | To reach this step, developers should have affirmed they understand the task sufficiently, and that this step can be accomplished in a short enough period of time to accomplish the successor steps. |
3. Review and merge code changes | Many agile teams have processes that involve peer-developers reviewing each others’ code changes before these are merged back into the “master” code branch. This provides opportunity to once again revisit the thoughts and decisions documented in the verbose CMS story notes, and it provides opportunity for teams to enforce coding standards. |
4. Deploy & test the new code | Following merge of the code, a build can be triggered and any conflicts can be resolved. |
5. Confirm the requirement is being met | Once the code changes are running in a pre-production environment, a change can be tested to confirm it is having the desired effect. |
It is hopefully becoming apparent that a Roadmap item, meaningful to an executive, lacks detail for the developer to realistically implement it. If a developer were to attempt to implement an entire Roadmap item in one shot, it would likely be too large of a change to handle in a typical sprint cycle. Breaking down Roadmap items, and documenting thoughts and decisions along the way, is an essential activity. Doing this well has sustainability rewards as well — when development eventually shifts to support, a central source for all this knowledge is invaluable.
DevOps Tools vs. Content Management Systems (CMS) for Requirements Management
DevOps tools enable the day-to-day operations of high-performing software development teams. CMSs, conversely, are incubators for unrefined high-level requirement concepts. When a CMS is leveraged to its fullest potential, high-level requirements are thoughtfully deconstructed into manageable work packages, and supporting knowledge and artifacts are organized to present clear, detailed direction to developers. A CMS can act like a firewall between the chaotic activities that occur while requirements are being prepared, and the structured, lean, high-performing DevOps environment. While BAs could write a detailed requirement with a sufficiently narrow scope in one of the aforementioned DevOps tools, these tools lack many useful features that a CMS provides. For comparison’s sake, let’s look at the capabilities of a DevOps tool for managing a requirement alongside the extended capabilities a CMS provides:
DevOps Capability | CMS Extended Capability
”—” = CMS has matching, but no additional capabilities
“X” = CMS is missing this capability |
Unique Work Items | — |
Work Item Titles | — |
Work Item Statuses | Additional status types can be used, including those that are applicable to the progress of BAs requirements refinement. |
Predecessor, successor, and other work-item-to-work-item relationships | — |
Due Date | Through relationships to CMS entities other than requirements, like related tasks, other dates can be rolled up to a requirement. This can help with planning when there are multiple, supporting deliverables needed for a requirement to be ready-to-develop (i.e. data model diagrams, API notes, UI mockups, etc.) |
Assignee | CMS users can include non-developer team members. BAs, SMEs, designers, and other team members can be assigned tasks in a CMS that has project management features, even if they do not use/are not licensed for the team’s DevOps tool. |
Type | Enables metadata tagging for additional deliverable types (user stories, acceptance criteria, UI/UX mockups, data model diagrams, development planning notes). |
Sizing (by planned hours, t-shirt size, story points, etc.) | — |
Comments (threaded or linear) | Provides comment/discussion of requirements pages, or specific lines of content within a page. |
Work Item to Code Repository Linking | X |
Work Item to Sprint Linking | X |
Description | Capable of embedding content inline from other sources, like UI mockup tools. Text editing features, section breaks (by topic/audience), and linked/sub-pages can be used to clearly present complex concepts.
|
The Tools
The ubiquity of CMS tools on the market today means most teams should be able to pick up an off-the-shelf tool for this purpose and hit the ground running. The preceding feature comparison gives a generic idea of features teams should look for. That said, here’s a shortcut to finding a great CMS for your team: check out Notion. Notion is the tool I’ve had the greatest success with when it comes to managing both the requirements backlog and all of the work associated with building the backlog. Its minimalism will be refreshing to anyone tired of trying to work with bloated wiki-style editors, and its flexibility will be exciting to anyone who has had to work within the rigid confines of a dedicated project management tool. I would compare its learning curve to using Microsoft Excel for the first time, but there are thriving community resources and experts who can help get the most out of the tool (including this post’s author).
| 9 Minute Read
6 Minute Read
| 7 Minute Read