6. Documentation
6.1. Rationale
Code review i dokumentacja
Architectural Decision Records
Składnia Markdown i reStructuredText
Systemy generowania dokumentacji
Code Review jako mechanizm przekazywania wiedzy
OpenAPI i SwaggerUI
CI/CD dokumentacji
Generowanie UML (Mermaid)
Generowanie diagramów klas, ERD
Spellchecking
6.2. Architectural Decision Records
Problem name
Status
Deciders
Date
Context and Problem Statement
Decision Drivers
Considered Options
Good, because [argument a]
Good, because [argument b]
Bad, because [argument c]
Decision Outcome
Pros and Cons of the Options
References
Moon Landing
============
* Status: accepted
* Deciders: Mark Watney, Melissa Lewis, Rick Martinez
* Date: 1961-04-12
Context and Problem Statement
-----------------------------
* We are doing this for all mankind
Decision Drivers
----------------
* Space Race between superpowers
* Political reason
* Inspiration
Considered Options
------------------
* Long duration spaceflight to orbital station
* Mars landing
* Doing nothing
Decision Outcome
----------------
* Neil Armstrong will set his foot on the Moon
Pros and Cons of the Options
----------------------------
Mars landing:
* Dangerous
* Requires much bigger budget
Orbital Station:
* Not spectacular
* Will not progress us as much as Moon landing
References
----------
* https://er.jsc.nasa.gov/seh/ricetalk.htm
* https://history.nasa.gov/afj/ap11fj/01launch.html
* https://www.history.nasa.gov/SP-4029/Apollo_11i_Timeline.htm
6.3. Assignments
Stwórz ADR dla Smoka
Pracujcie nad decyzją w grupach trzyosobowych