# TAD <name of your project>

## Introduction
### Context

In this section you need to describe the context of your project as discussed with your PO during the TDD kick-off. You will sum-up the business requirements and objectives which will have an impact on your Technical Analysis. This section is important as it will justify your technical choices.
You can link documents to the one pager made by your PO.
Why are you doing this project ? What does it solve ? How we were doing it before ?

### Keys of success

List here the technical success criteria which are going to make your TDD valid for the achievement of your project. These are derived from your business requirements.

## Technical Analysis
Every dev have its own style for writing a TDD. Here is the advised methodology. And there is nothing better than code to explain the principle:

type Capability = string;
type TechRequirement = string;
type Criteria = string;
type Advantage = string;
type Risk = string;

type Solution = {
  describe(): string;
  getCapabilities(): Capability[];
};

type Problem = {
  describe(): string;
};

type Project = {
  getProblemsOrChallenges(): Problem[];
  getTechRequirements(): TechRequirement[];
};

type CriteriaEvaluation = {
  criteria: Criteria;
  advantages: Advantage[];
  risks: Risk[];
};

type Author = {
  findAllPossibleSolutions(problem: Problem, options: { limit: number; orderBy: string }): Solution[];
  findCriterias(requirements: TechRequirement[], problem: Problem): Criteria[];
  discoverNewCriteria(capabilities: Capability[]);
  analyzeSolution(criterias, solution): CriteriaEvaluation[];
  printComparisonTable(evaluations: CriteriaEvaluation[]): string;
};

const tad = (author: Author, project: Project) => {
  let content = ``;
  const techRequirements = project.getTechRequirements();
  const problems = project.getProblemsOrChallenges();

  problems.forEach((problem) => {
    content += problem.describe();
    const initialCriterias = author.findCriterias(techRequirements, problem);
    const solutions = author.findAllPossibleSolutions(problem, { limit: 3, orderBy: 'relevance' });

    const criterias = solutions.reduce((allCriterias, solution) => {
      return [...allCriterias, ...author.discoverNewCriteria(solution.getCapabilities())];
    }, initialCriterias);

    solutions.forEach((solution) => {
      content += solution.describe();
      const evaluations = author.analyzeSolution(criterias, solution);
      content += author.printComparisonTable(evaluations);
    });
    
    content += author.suggestASolution(solutions);

    return content;
  });
};

The algorithm is simple, and what we need you is to implement the Author type thanks to your super-powered brain.
And what follows is a potential output of the TAD

### Problem 1: How to make objective decisions in a TDD ?

The aim of a TDD is to provide a the best Technical Design to a list of requirements. Engineers tend to have personal opinion about a solution which is often based on either their own experience or what they heard about a technology. We all have bias.
So, how can we take objective decisions without beeing affected by our personal bias?

#### Solution A: Provide multiple solutions to the team and take a collective decision

By providing multiple solutions, we force ourself to brainstorm on multiple alternatives even if we have a strong instinct. Taking the decision as a team as the advantage of sharing the various knowledge and experience of the team on this specific subject.

| Facts | ? | Comment |
| -------------------- | --------- | ---- |
| decision objectivity | :heavy_check_mark: | As multiple persons are involved this can take time|
| knowledge sharing | :heavy_check_mark: | This is not a requirement to produce a TDD, but an opportunity |
| scientific decision | :no_entry_sign: | Decision process is only based on team experience |
| respect our specific requirements | :heavy_check_mark: | |

#### Solution B: Compare solutions by rating them based on how it answers to requirements.

The decision process could be based on factual data. We could evaulate each solutions based on how it is able to solve each requirement. Evaluation could be a rating, or a fact check (yes/no) as it is done in the table below.

| Facts | ? | Comment |
| -------------------- | --------- | ---- |
| decision objectivity | :heavy_check_mark: | |
| knowledge sharing | :no_entry_sign: | |
| scientific decision | :heavy_check_mark: | |
| respect our specific requirements | :heavy_check_mark: | |

#### Solution C: Based it on the web popularity

Looking at the popularity of a solution on the web could help take a decision and could help us during the implementation phase.

| Facts | ? | Comment |
| -------------------- | --------- | ---- |
| decision objectivity | :no_entry_sign: | There is a lot of hype on some technologies. It is not because it is popular that it makes it a good solution for our project / industry. |
| knowledge sharing | :warning: | communtity feedback could help us prevent doing the same mistake. But are we having the same problem at first ? |
| scientific decision | :no_entry_sign: | |
| respect our specific requirements | :no_entry_sign: | Maybe it does? but most of the time, it does not. |

#### Suggestion
These solutions are not mutual exclusive. I would recommend to follow solutions A and B as ...

| Requirements / Solutions | A | B | C | A &amp; B |
| -------------------- | --------- | ---- | ---- | ---- |
| decision objectivity | :heavy_check_mark: | :heavy_check_mark: | :no_entry_sign: | :heavy_check_mark: |
| knowledge sharing | :heavy_check_mark: | :no_entry_sign: | :warning: | :heavy_check_mark: |
| scientific decision | :no_entry_sign: | :heavy_check_mark: | :no_entry_sign: | :heavy_check_mark: |
| respect our specific requirements | :heavy_check_mark: | :heavy_check_mark: | :no_entry_sign:| :heavy_check_mark: |

### Problem 2: Which tool should I use to write my TDD ?
Teams have been using different tools to write TDDs. We need to align teams on a single format.
#### Solution A: Miro
#### Solution B: Confluence
#### Solution C: Markdown

##### Problem 2.1: What tool should I use to edit Markdown ?
###### Solution A: My IDE and Merge Request
###### Solution B: HackMD

#### Suggestion
We should use Markdown with the HackMD editor as it provides all the advantages we are looking for:
| Requirements / Solutions | Miro | Confluence | Markdown (IDE) | Markdown (HackMD) |
| -------------------- | --------- | ---- | ---- | ---- |
| standardized output | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: |

### Problem 3: Where to publish ?