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