Skip to content

Commit

Permalink
Analysis and design documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
t2gran committed Nov 26, 2024
1 parent bc3147f commit 7df8f99
Show file tree
Hide file tree
Showing 3 changed files with 61 additions and 0 deletions.
6 changes: 6 additions & 0 deletions DEVELOPMENT_DECISION_RECORDS.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,12 @@ Use established terminology from GTFS, NeTEx or the existing OTP code. Make sure
to read and understand. [Follow naming conventions](doc/dev/decisionrecords/NamingConventions.md#naming-conventions) .


## Do Analysis-and-design if needed

Be prepared to provide [analyses and/or design documentation](doc/dev/decisionrecords/AnalysesAndDesign.md)
if a task is complex, changes the core model and/or the main APIs.


## Write-Code-Documentation - Use JavaDoc

Document the business intention and decisions in the relevant code. Do not repeat the logic
Expand Down
51 changes: 51 additions & 0 deletions doc/dev/decisionrecords/AnalysesAndDesign.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,51 @@
# Analysis and design

We want to get better at design, so we want some documentation up font for large changes. If a
problem is complex, changes the core OTP model, and/or the API significantly, then the developer
requesting a change should be prepared to provide some design documentation.

The analysis should be started and at least mapped out in an issue. The design can be documented
in the issue or the PR.


## Analysis & Design

A discussion in a developer meeting is usually a good point to start.

- Ask what is expected?
- Diagrams beat words in most cases, and help focus on the problem - not implementation details.


### Artifacts

We usually do not require a long list of requirements and analyses documentation. But these
artifacts may help, none of these are required. Ask in the developer meeting what to expect.

- [ ] Summarise the discussion in the developer meeting in the issue or PR.
- [ ] List use-cases, one sentence per use-case is often enough.
- [ ] In/out matrix, list features you are NOT planning to implement.
- [ ] Draw diagrams
- [ ] **Domain model** — If the core model or APIs are significantly changed
- [ ] State diagram
- [ ] Collaboration diagram


## Domain model

A domain model focus on the language and the relationships. All implementation details can be left
out. Details witch is not relevant for the problem you are solving can also be left out, focus on
the elements witch helps understand the problem. Use plain english and not tech to describe
the model. For example, only listing the field name, and not the type is ok if the type is obvious.

Notation is not important, but try to follow the UML syntax below. You may use more advanced UML
syntax if you want, but keep in mind that you should be able to use the diagram to discuss the
problem with a none developer. A product-owner or other person who knows the domain should with
a little help be able to understand the main parts of the drawing.

When doing review, focus on the domain problem, not syntax — ask about things you do not understand.


### Domain model - notation cheat sheet

![Domain Model Notation](../images/DomainModelNotation.svg)

4 changes: 4 additions & 0 deletions doc/dev/images/DomainModelNotation.svg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.

0 comments on commit 7df8f99

Please sign in to comment.