Architecture Decision Records are commonly used across engineering teams to document and retain knowledge around decisions pertaining to the functional or non-functional decisions of a product. While these decision records can be successful, they can also leave out critical details pertaining to product requirements that influence architecture decisions; in addition, these documents are typically owned by and involve only the engineering teams, which can in turn alienate a core component of the team, Product. At Target, we've consolidated both product requirements and architecture decisions into a single record called Feature Document (Feature Doc) where we document, design, collaborate, and align on product feature architecture(s).
What’s a Feature Doc?
A Feature Doc, similar to an Architecture Decision Record, is a record outlining a deliverable, whether functional or non-functional. It is designed to be easy to use and read, and a reference point for all members of the team whenever they need to understand what is being delivered or what was delivered. The Feature Docs are maintained over the lifecycle of the product to understand the historical decisions made by the team and to avoid repeat failures or share lessons learned. When building upon existing Feature Docs, engineers are equipped to quickly pick up any component of the architecture and append to it, thus enabling rapid development. As the team continues to grow, the time required to onboard teams can often be a big lift to not only new team members but also existing team members moving laterally. A historical record of Feature Docs provides insight into the lifecycle of the product and reduces the overall onboarding time by enabling new team members to read and comprehend the architecture quickly.
At the crux of it, the Feature Doc is intended to accomplish 3 things:
- Establish alignment on the feature goals, scope, design, architecture, and delivery approach for a specific feature across the team (product, engineering, and leadership).
- Serve as a means of communication for deliverables and establish an epic-level roadmap for the feature.
- Establish a set of expectations and engineering excellence with the engineering team.
Alignment
We templated the Feature Doc for consistency over time and defined "section" owners for role and responsibility clarity. To ensure the team is aligned on the feature being developed, the first task of any Feature Doc is for the Product Manager to define the purpose, define the scope, and set up some high-level project details (i.e., epic, dates, dependencies, etc.). This gives the engineering team the ability to understand the expectations, ask questions, and relate to the users who benefit from the deliverable.
Task 1: Feature Overview and Feature Scope
Once the overview and scope are defined and agreed upon, the implementing engineer(s) will either design a new Feature Doc or build upon existing Feature Doc architecture diagrams. This includes a reference architecture, outlining user flows, defining API implementations, defining any modeling, etc. to ensure the engineering team has a comprehensive understanding of the implementation path. While this level of detail feels extensive, it provides an avenue of communication for engineers through leadership to have a full understanding of the direction to ensure collaboration across all teams within the organization.
Task 2: Architecture and Implementation
Once the architecture and implementation are agreed upon, the team will collaborate on a release strategy. The release strategy ensures both product and engineering have what they need documented to either trigger CI/CD tools, communicate to users, or any other relevant needs.
Task 3: Release Strategy
Once all 3 tasks are complete, the full team will have an understanding of the value of the feature, the architecture and implementation details of the feature, and how this feature will be released to users. Like a code review, the team will treat the Feature Doc as code and complete a review with an approval process before moving forward with the implementation.
Communication
The Feature Doc is a common means of collaboration, presentation, and overall communication of the work being done which in turn drives a roadmap for the team. To highlight the impact a Feature Doc can have in driving and improving the communication, listed below are common asks of any team that the Feature Doc helps with:
- As more and more Feature Docs are written, a part of the delivery of a Feature Doc is to write stories / tasks to execute against the implementation. This then removes the need for full team backlog refinement meetings and populates the backlog with all necessary work required to complete the feature. Overall, the Feature Doc enables the team to pick any backlog item and have a wealth of knowledge on how to complete the work.
- Often, Product or Engineering are asked to present the work being done and this ask leads to additional work to collect several meeting minutes, pictures, and code, together to highlight the work being done. The value of the Feature Doc is that all information pertaining to the work being done is collected in one central spot. In addition, the Feature Doc is open to all of Target’s team members for comments and collaboration to incentivize and build a "learn in public" culture.
- A Feature Doc has also proven its value as a means of team-to-team communication. As teams build APIs, Kafka topics, and other products, a contract is often established between teams. Leveraging the Feature Doc as the contract not only provides transparency into the contract but also highlights how the contract will be implemented.
A Feature Doc is a consistent and consolidated means of communication that streamlines several procedures faced within the tech industry. It simplifies expectations and is a clear deliverable that empowers everyone to communicate and collaborate.
Expectations and Engineering Excellence
To drive accountability across the team, the Feature Doc establishes a set of expectations with a focus on engineering excellence. To expand on this notion, engineering excellence can mean many things but in this context it means - Professionalism, Platform / Customer Focus, and Growth Mindset.
The Feature Doc gives engineers the ability to learn new skills, expand their knowledge around Target tech, and expand their understanding of the existing architecture. In addition to learning, engineers can expect their peers to challenge, question, and review the implementation to ensure platform stability and customer satisfaction is maintained. The Feature Doc is reviewed by the team, like code, for maintainability and alignment; but it's also a means of accountability. Just like code, we are held accountable for the quality, and sustainability of the code authored, and a Feature Doc is no different. It's an artifact of the product that is depended upon and we, as a team, are held accountable for completing it in its entirety.
To ensure accountability, as the Feature is delivered and the epic of work is completed, the Feature Doc is revisited to ensure we've not only met the requirements, but also that all documentation is accurate and set up for the next iteration. This activity is a level of professionalism to ensure that as we hand off work to the next product manager or engineer, it's set up for quick iteration.
The Feature Doc is a living body of work and accomplishment of the team. It highlights technology, architecture, and engineering practices that can be referenced as the team recaps and celebrates its accomplishments for the year. As Feature Docs are collected over time, the team can reference these documents to highlight their deliverables. Often times, team members have leveraged Feature Docs as a point of reference to highlight their ability to design or architect as they are considered for promotions or lateral moves.
The Feature Doc in Practice
Aligning with the Agile Manifesto, Feature Docs are working documents and iterated upon throughout the development cycle. Treating documentation like code has allowed each member of the team to contribute and stay aligned, all while working asynchronously across multiple work streams and driving towards a consistent sprint velocity. By spending a little time upfront to document, approach, and collaborate, we've been able to anticipate change and collaborate with our user base to enable quick and rapid releases. And, as requirements or needs change we adjust and document those to keep the documentation relevant to the scope of the feature.
Feature Doc Flow
A basic flow for a Feature Doc is as follows:
- The product manager or engineer creates a new template and completes the Overview and Project scope sections. This ensures that the feature is tied to a defined goal, problem to solve, and has a clear scope.
- The engineer completes the architecture design and/or the UX flow/mockups.
- The team reviews the doc, including scope, design, and mocks to ensure visibility to the feature, get clarity on assumptions or scope, and agree on the proposed architecture and UX.
- An epic is created in the scrum board and the engineer writes the stories necessary to complete the agreed-upon architecture.
- As the feature gets built, the Feature Doc is updated with new information, decision changes, and updates to scope.
Summary
With over two years of using the Feature Doc as a standard practice for our scrum teams, a few key benefits have emerged:
- Increasing alignment. Increased velocity.
As we continue to evolve our work processes, we've found that the asynchronous nature of the feature page has allowed us to work extremely efficiently, minimizing overhead and governance while maximizing alignment and design decisions. As we operate within 1-week sprints, we average near 80% completion ratio of all stories with carry over routinely involving deliverables near completion.
- Empowering all levels of engineers
The Feature Doc can be created, reviewed, and managed by anyone on the scrum team, from a principal engineer to an entry-level engineer. Even our engineering interns have leveraged the Feature Page to self-sufficiently document and guide the direction of a feature, all with the right level of oversight and support.
- Integrating across products is a breeze
The ability to collaborate on a single page has been a boon when two separate engineering teams need to partner together on a single feature or integration. Ensuring architectural alignment, dependencies, etc. helps ensure that we stay in synch without the need for endless meetings or more "scrum-of-scrums" calls.
- Getting leadership the info they need
Linking the product definition, goals, and scope to the architecture in a single document has made communicating with executive leadership as easy as sending a one-pager. Whether it's business teams, engineering leadership, or product leadership, there's no last-minute scrambles to "prepare a deck" to explain what we're working on.
The Feature Doc is a tool to ensure the team is bought into the vision and takes ownership and pride in the outcome being delivered, and it empowers Target teams with the ability to align, communicate, and hold each other accountable to a set of expectations. As a living body of work, decisions and architecture, teams are able to easily and quickly onboard new team members, highlight the value of their work, or transition work amongst themselves. Several teams have adopted the Feature Doc with much success, and we continue to see the adoption grow throughout Target.