130: Team Growth in the Modern Workplace
Modern workplace, agile teams and slicing user stories
Thank you for reading Snippets of Text. Snippets from media about tech, programming, parenting, and more. This is a preview of a post available exclusively to paying subscribers. You can get unlimited access to all articles by purchasing a subscription.
Unrelated: Streamlining Decision-Making in Software Engineering
Whenever a team member identifies a decision of this nature, they should create an ADR. Templates can be used to simplify the creation process and ensure that all relevant information is captured.
The team member creating an ADR becomes its owner and handles maintaining and communicating its content. The ADR is provided in the "proposed" state, indicating it is ready for review. The owner then arranges a team meeting to discuss and determine whether the ADR is accepted, requires rework, or is rejected. If the team believes the ADR needs improvement, it remains "proposed", and the owner and other team members collaborate on refining it. Otherwise, if the ADR is accepted or rejected, its status becomes immutable. If the team needs to update the decision, they should propose a new ADR, which, upon acceptance, supersedes the previous one.
Architecture for agile projects needs to be described and defined. Yet, not all decisions have to be made at once or at the beginning of a project. Agile methods do not oppose documentation; they oppose documentation that lacks value. Documents that assist the team can be valuable, but only if they are kept current. Large documents must be updated, whereas smaller, modular papers have a better chance of being maintained. Large documents are often left unread due to their size, making them challenging to open, read, or edit. All stakeholders consume bite-sized pieces of information.
When new team member joins a project, they may feel perplexed, baffled, delighted, or infuriated by past decisions. This response can be acceptable if the decision remains valid but may need revisiting if the context changes. Individuals need to grasp the rationale and consequences of having different choices. Each ADR describes a set of forces and a single decision responding to those forces. While decisions are not patterns, they involve balancing various factors.
The decision takes center stage, and specific forces may appear in many ADRs. ADRs should be stored in the project repository under the "doc/arch/adr-NNN.md" directory, using lightweight text formattings languages such as Markdown or Textile. ADRs are numbered, and numbers should not be reused. The old ADR should be retained but marked as superseded if a decision is reversed. The document structure should consist of several parts to ensure easy digestion.
Title: The document titles should be concise noun phrases, such as "ADR 1: Deployment on Ruby on Rails 3.0.10" or "ADR 9: LDAP for Multitenant Integration".
Context: This section describes the forces at play, including technological, political, social, and project-specific factors. These forces are in tension and should be identified. The language used in this section should be neutral, describing facts rather than opinions.
Decision: This section outlines the team's response to the identified forces. The decision's status may be "proposed" if it has not yet been agreed upon by project stakeholders or "accepted" if it has been
Approved: If the next ADR alters or reverses a decision, the original decision should be marked as "deprecated" or "superseded" in favor of the new one.
Consequences: This section describes the resulting context after implementing the decision. All results, including positive, negative, and neutral ones, should be listed here.
Each ADR should be written as a conversation with a future developer, requiring a clear and well-structured writing style with complete sentences organized into paragraphs. Bullets can be used for visual style but should not be an excuse for writing sentence fragments. Each ADR should address a significant decision for a specific project, influencing the project's direction.
The consequences of one ADR often become the context for the next ADRs, akin to Alexander's idea of a pattern language where larger-scale responses create spaces for smaller-scale elements to fit in. ADRs provide visibility to developers and project stakeholders, even as the team composition changes, ensuring that the motivation behind previous decisions remains accessible to everyone, present and future.
Off Topic: User Story Slicing for Complex Projects
Big user stories, classified as **L (large)** or with effort points exceeding **6**, can enjoy this approach. Dividing a user story into tasks to reduce its scope may lead to the emergence of unrelated issues.
Even when a user story is divided, each task may need to be more significant. A more effective approach would be to use scenarios and context to gauge effort. Suppose there are gaps in either aspect, indicating that the user story is too big. In that case, creating epics to encapsulate several smaller stories may be necessary instead of a single story with many more minor tasks.
Keep reading with a 7-day free trial
Subscribe to Snippets of Text to keep reading this post and get 7 days of free access to the full post archives.