Software Architecture Books Summary And Highlights -- Part 4 Team Work And Communication

 

Team Work And Communication 

Highlights

Talk to domain experts

The best way is to let developer collaborate with domain experts leading by developer so that

1. can gain quick feedback on domain model
2. force domain expert to refine their own understanding by being forced to distill what they know to essentials

DDD ch1 crunching knowledge

How to interview stakeholders to gather core requirements:

• Stakeholders are sometimes not clear about QA requirements
  • Architect can play dumb. e.g. if they don’t know what time requirement is needed, just ask them if 1hr is ok, 30 minutes is ok …. until they seem to be happy with the number.
• The Quality Attribute Workshop
  1. Stakeholders present business requirements including known QA requirements
  2. Architect presents current design and plan
  3. Identification of architectural drivers.
     1. The facilitators will share their list of key architectural drivers that they assembled in the prior two steps,
     2. and ask the stakeholders for clarifications, additions, deletions, and corrections.
     3. The idea is to reach a consensus on a distilled list of architectural drivers that include overall requirements, business drivers, constraints, and quality attributes.
  4. Scenario brainstorming: each stakeholder present one scenario
  5. Scenario consolidation: merge these scenario
  6. Scenario prioritization
  7. Scenario refinement

SAP Ch 19 Architecturally Significant Requirements

Ubiquitous language

• is used to create a supple, knowledge-rich design.
• should be a versatile, shared team language, and a lively experimentation with language that seldom happens on software projects.
• force the model’s weaknesses into the open. The team will experiment and find alternatives to awkward terms or combinations.
• changes to the language will be recognized as changes in the domain model and will lead the team to update class diagrams and rename classes and methods in the code, or even change behavior, when the meaning of a term changes.
• In meetings, use domain model’s term and language as much as possible instead of technical terms such as database

DDD Ch2 communication and language

Continuous Integration

When a number of people are working in the same BOUNDED CONTEXT, there is a strong tendency for the model to fragment.

Solution:

• Institute a process of merging all code and other implementation artifacts frequently, with automated tests to flag fragmentation quickly.
• Relentlessly exercise the UBIQUITOUS LANGUAGE to hammer out a shared view of the model as the concepts evolve in different people’s heads .

DDD ch 14 Maintaining Model Integrity

Communication with User

When a design is based on a model that reflects the basic concerns of the users and domain experts, the bones of the design can be revealed to the user to a greater extent than with other design approaches. Revealing the model gives the user more access to the potential of the software and yields consistent, predictable behavior.

DDD Ch 3 Binding Model and Implementation

Conway’s Law

Any organization that designs a system (defined more broadly here than just information systems) will inevitably produce a design whose structure is a copy of the organization’s communication structure.

small teams can work faster than large team. Amazon wants each team to own whole life cycle of the product

When the cost of coordinating change increases, one of two things happen. Either people find ways to reduce the coordination/communication costs, or they stop making changes. The latter is exactly how we end up with large, hard-to-maintain codebases.

MSV Ch 10 Conway’s Law and System Design

Internal open sources:

Allow other team to change a service but require code review by core owners.

Most open source projects tend to not take submissions from a wider group of untrusted committers until the core of the first version is done.

If a service is pretty mature, and is rarely changed — for example, our cart service — then perhaps that is the time to open it up for other contributions.

If your team structures are aligned along the bounded contexts of your organization, then even services that are not changed frequently still have a default owner who owns the large scope

MSV Ch 10 Conway’s Law and System Design

Expose work early

People can feel insecure and hide their code during development

It is better to expose your work as early and frequent as possible than hiding them so that you can get good feedbacks.

SWG ch 2 how to work well on a team

Documentation

UML diagram has limitations. It lacks ability to describe behavior. It is suitable to describe the model in a simple way. But the model is not the diagram

The code is the best content to describe the all business logics and details. Doc can be left behind. So doc is just supplement to code which could explain the concepts of the model, help in navigating the detail of the code, and perhaps give some insight into the model’s intended style of use.

By keeping documents minimal and focusing them on complementing code and conversation, documents can stay connected to the project.

We can have explanatory model to help communication and education.

The technical model that drives the software development process must be strictly pared down to the necessary minimum to fulfill its functions. An explanatory model can include aspects of the domain that provide context that clarifies the more narrowly scoped model. Explanatory models offer the freedom to create much more communicative styles tailored to a particular topic.

DDD Ch2 communication and language

Architecture Documentation Practical Considerations

1. Versioning your document and follow document release process
2. Documenting architectures that change dynamically, e.g. dynamic discovery, frequently released system
   1. Document what is true about all versions of your system.
   2. Document the ways the architecture is allowed to change.
   3. Generate interface documentation automatically.
3. Traceability: link design doc to Product requirement doc

SAP Ch 22 Documenting an Architecture

Guideline for team work:

1. Update documentation when you read it. Because people who wrote it might be too familiar with the topic and might miss some subtle but critical info for beginner.
2. Create doc in searchable place and allow comments and feedback
3. Promote documentation because it helpful to both the individual, the team and other teams
4. code doc is also important

SWG ch 3 knowledge sharing

Documentation purpose

Keep documents focused on one purpose.

Audience

applies as broadly to your different audience groups as possible to both expert and novice

Need a balance between expert and novice audience. So 2 passes

1. write descriptively to explain complex topic clearly for novice
2. removing duplicate information where you can to shorten the doc for expert

Another audience distinction

1. seekers: who know what they want, just look for info. Make the doc consistent with same format for them
2. stumblers. who don’t know what they want. clarity is important to them. e.g. overviews, TL;DR

Another audience distinction:

1. api user: no implementation details
2. api owner/maintainer : implementation details in design doc

SWG ch 10 Documentation

Document Types

• Reference doc
  • File comments
    • Begin with a short overview paragraph of this file.
    • If it is hard to make the overview short, then probably the api design is bad and need to break the file into multiple components
  • Function comments:
    • begin with a verb to helper seeker quickly scan
• design doc:
  • contents:
    • design goal
    • implementation strategy
    • key decision result with trade offs
    • alternative approach with pros cons
• conceptual doc:
  • Emphasize clarity
  • conceptual overview of some other docs
• landing page:
  • team introduction page for other teams
  • contains only an overview and links to other docs

SWG ch 10 Documentation

Documentation review:

• technical review
• audience review
• writing review

SWG ch 10 Documentation

Documentation philosophy

Redundancy is helpful to convey important points

Tradeoff among completeness, accuracy, clarity based on doc purpose.

To improve a doc, often less is better

SWG ch 10 Documentation

Team relationship

3 team work pillars:

1. humility,
2. respect: You genuinely care about others you work with. You treat them kindly and appreciate their abilities and accomplishments.
3. Trust: You believe others are competent and will do the right thing, and you’re OK with letting them drive when appropriate.

Learn to respect your peers and give constructive criticism politely. If you truly respect someone, you’ll be motivated to choose tactful, helpful phrasing—a skill acquired with much practice.

work in isolation is needed for coding but will make people think you are hard to communicate with. So be careful about the tradeoff

be open to influence: if you are too stubborn , and people will stop to listen to your opinion or objections. So listen and understand other people first.

listen before putting a stake in the ground or firmly announcing a decision—if you’re constantly changing your mind, people will think you’re wishy-washy.

Willing to admit your mistake because your coworkers are your collaborator instead of your competitors

SWG ch 2 how to work well on a team

How to lead a team

if a manager makes it obvious that they trust their employee, the employee feels positive pressure to live up to that trust.

Anti pattern :

• Hiring people who is worse than you: you should hire people who can replace you
• Ignore low performers: will make high performer leave
• Try to be friend to everyone
• Treat your team like children
• Compromise the hiring bar
• Ignore human issue

Positive patterns:

• Lose ego
  • Trust your teammate, give them accountability
  • Encourage inquiry and challenge
  • Willing to apologize
• Be zen master
  • Be calm and less skeptical because your small mood can affect your subordinates
  • Give your teammate advice by asking them questions
• Be a catalyst and build consensus smoothly
• Remove roadblock
• Be a teacher and a mentor
• Set a clear goal by creating concise mission statement
• Be honest
  • Admit what you don’t know
  • Give hard feedback with compliment tone
• Track happiness
• Delegate, but get your hands dirty by by taking on a grungy task that no one else wants to do
• Seek to replace yourself
• Act quickly to any human problem and don’t wait
• Shield your team from external chaos
• Defend your team from a lot of the uncertainty and frivolous demands
• Let your team know when they’re doing well
• It’s easy to say “yes” to something that’s easy to undo
  • allow your team member to try and fail small things but be careful on important things

SWG Ch 5 how to lead a team

Related Chapters

DDD Ch 1 crunching knowledge

DDD Ch 2 communication and language

DDD Ch 3 Binding Model and Implementation

DDD ch 14 Maintaining Model Integrity

SAP Ch 19 Architecturally Significant Requirements

SAP Ch 22 Documenting an Architecture

MSV Ch 10 Conway’s Law and System Design

SWG ch 2 how to work well on a team

SWG ch 3 knowledge sharing

SWG ch 4 Engineering for Equity

SWG Ch 5 how to lead a team

SWG Ch 6 leading at scale

SWG ch 10 Documentation