Dokumentacja,
która sama się pisze

@technites_pl

Trzy rodzaje dokumentacji

@technites_pl

Podobno wszystko tu miało być

Trzy rodzaje dokumentacji

To na pewno
gdzieś tu jest

@technites_pl

Trzy rodzaje dokumentacji

@technites_pl

To nasz najnowszy model
... jedynie 30 lat temu

Po co nam w ogóle dokumentacja ?

@technites_pl

Nie wnikaj, taki mamy wymóg

Po co nam w ogóle dokumentacja ?

@technites_pl

Musimy to pokazać na spotkaniu

Po co nam w ogóle dokumentacja ?

@technites_pl

A może zespół jej potrzebuje ?

Tylko czego on w zasadzie potrzebuje ?

Codzienne pytania

@technites_pl

  • Architekt:
    Jaka jest relacja między jednostkami wdrożeniowymi
    a granicami modelu domenowego ?
  • Lider zespołu:
    Z jakimi innymi modułami integrują się moduły, którymi opiekuje się mój zespół ?
  • Deweloper:
    Jakie elementy modelu domenowego realizują ten
    use case i jakie struktury w kodzie je implementują ?

Codzienne pytania

@technites_pl

  • Product Owner:
    Jakie zespoły są zaangażowane w ten proces ?
  • Tester:
    Jakie reguły są pilnowane przez elementy,
    które realizują ten use case ?
  • Ekspert domenowy:
    Na jakie procesy będzie wpływała zmiana tego elementu modelu ?
  • etc., etc., etc.

Co jest pod spodem ?

@technites_pl

Co jest pod spodem ?

@technites_pl

Na sprint review niestety nie widać wszystkiego

Szerszy kontekst

Dziwne, każda historyjka osobno wyglądała dobrze ...

@technites_pl

Wspólna reprezentacja

@technites_pl

Gdyby można było zobaczyć efekt,
zanim będzie
za późno ...

Spojrzenie z innej perspektywy

@technites_pl

Kod nie zawsze jest
optymalną reprezentacją

@technites_pl

zrozumienie biznesu i
aktualnego rozwiązania

Software development is a learning process,
working code is a side effect.

- Alberto Brandolini

szybsze i bezpieczniejsze
dostarczanie na produkcję

@technites_pl

Dokumentacja powinna zapewniać
efektywny wgląd w projektowany system

we wszystkich jego aspektach

dla osób o różnych kompetencjach

Skoro to takie ważne,
to dlaczego dobrej dokumentacji (prawie)zawsze brakuje ?

@technites_pl

  • brak świadomości ?
  • lenistwo ?
  • natłok pracy ?

A może przyczyna jest gdzieś głębiej ?

Jak to wygląda
w budownictwie ?

@technites_pl

Jak często wprowadzane są zmiany?

A jak to wygląda
w IT ?

@technites_pl

Jak często wprowadzane są zmiany?

public class Order
{
    public void Place()
    {
        ...
    }
    
    ...
}

public interface DiscountPolicy
{
   ...
}

@technites_pl

Dlaczego tak jest ?

Manufacturing is a popular metaphor for software development [...]
This metaphor has messed up a lot of projects for one simple reason

- software development is all design.

-Eric Evans

@technites_pl

Pełna dokumentacja nie może
powstać przed kodowaniem

bo projektowania nie da się oddzielić
od implementacji

Aktualna dokumentacja nie może
powstać po implementacji,

bo zmiany są zbyt częste

Dokumentację powinno
dać się wygenerować z kodu

@technites_pl

most knowledge is already there

- Cyrille Martraire

living

=

samoaktualizująca

Dokumentację powinno
dać się wygenerować z kodu

@technites_pl

  • struktura typów
  • struktura katalogów
  • testy automatyczne
  • API
  • Infrastructure as Code
  • tracing
  • git
  • ...

A może kod wygenerować
z dokumentacji ?

@technites_pl

Ciężko jest
automatycznie uzupełnić brakujące informacje

Prawo automatycznych transformacji

@technites_pl

\forall f: f(code) = doc
f(.....) =

@technites_pl

@technites_pl

Tylko kod ma gwarancję aktualności, więc wokół niego trzeba zbudować narzędzia zapewniające wgląd w projektowany system

Żeby było to możliwe
kod musi mieć strukturę opartą o
dobrze zdefiniowane abstrakcje

Wieloznaczność terminów

@technites_pl

Problem jest w tym,
że nasze abstrakcje nie są jeszcze
dobrze usystematyzowane:

  • serwis
  • komponent
  • moduł
  • kontener
  • test jednostkowy
  • ...

Odrzucenie abstrakcji nie jest
rozwiązaniem tego problemu

@technites_pl

Kod z abstrakcjami
nie gwarantuje czytelności

Kod bez abstrakcji
gwarantuje brak czytelności

@technites_pl

To co potrzebne
do zrozumienia

To co potrzebne
do kompilacji

Czy w kodzie jest wszystko czego potrzebujemy ?

Metadane w kodzie

@technites_pl

[DddAggregate]
[CoreConcept]
public class Order
{
   ...
}

[DddValueObject]
public class Offer
{
   ...
}
# ADR 007

## Kontekst
...

## Decyzja
...

## Alternatywa
...
[CqrsCommand]
[BusinessProcess("WholesaleOrdering")]
public class PlaceOrder
{
   ...
}
[GofAbstractFactory]
[Exemplary]
public class PricingPolicies
{
   ...
}
[assembly:DeployableUnit("Search", "ADR 007")]
[assembly:Tier(ThreeTiers.Application)]
[PublicContract]
public class PassengerType
{
   ...
}

Metadane w kodzie

@technites_pl

@technites_pl

Brakujące informacje lepiej
dodać do kodu
w postaci metadanych,

niż pozwolić im dezaktualizować się
z dala od niego

Skala wyzwania

@technites_pl

  • wiele rodzajów informacji
    • domena
    • projekt techniczny
    • ludzie
  • wiele osób o różnych kompetencjach
    • deweloperzy
    • architekci
    • analitycy
    • testerzy
    • eksperci domenowi

Powrót do korzeni

@technites_pl

A software architecture is a complex entity that cannot be described in a simple
one-dimensional fashion

  • pierwsze artykuły - 1974
  • 4+1 - 1995
  • Siemens Four View model - 2000
  • CAFCR - 2005

Jak to jest
w innych branżach ?

@technites_pl

wikipedia.org

chiefarchitect.com

rodzaj mapy = perspektywa

@technites_pl

np:

  • granice modelu domenowego
  • jednostki wdrożeniowe
  • podział na zespoły

@technites_pl

abstrakcje + metadane w kodzie

automatyczne parsowanie

surowe dane do dokumentacji

wgląd z różnych perspektyw

narzędzia do wizualizacji

@technites_pl

Na system można patrzeć
z wielu perspektyw

Do jego zrozumienia
potrzebujemy ich wszystkich

Remanent narzędzi

@technites_pl

@technites_pl






 





 
Domain
Technology
People
Living

@technites_pl

Logs

Metrics

Traces

Observability

Połączone narzędzia potrafią więcej

@technites_pl



 

P3 Model
Domain
Technology
People
Living

3 perspectives

@technites_pl

Potrzebujemy dokumentacji

żeby efektywnie rozwijać systemy

a to co mamy zwykle nie jest zbyt użyteczne

Nie chcemy jej robić ręcznie

bo wtedy jest wiecznie nieaktualna

Musimy generować ją z kodu

Kod musi mieć czytelną strukturę
i metadane

@technites_pl

Mamy do tego gotowe narzędzia

ale żadne z nich nie obejmuje wszystkich aspektów

Potrzebujemy czegoś więcej

P3 Model

Domain - Technology - People

Zapraszamy Was do tworzenia P3

 

Wspólnie rozwiążmy problem nieaktualnej
i bezużytecznej dokumentacji

@technites_pl

P3 Model

GitHub P3-model

Przykład użycia
GitHub DDD-starter-dotnet

Testowanie architektury

(bonus)

@technites_pl

Mając informacje o zamierzonych wzorcach,
można automatycznie przetestować,
czy kod jest z nimi zgodny

Może w tym pomóc np:

noClasses().that().resideInAPackage("..Core..")
    .should().dependOnClassesThat().resideInAPackage("..UseCases..")

Code Review

(bonus)

@technites_pl

Mając informacje o modelu domenowym, sposobie wdrażania, scenariuszach biznesowych, etc.
można automatycznie wykrywać:

  • nowe pojęcia domenowe
  • reguły, które zostały usunięte
  • nowe zależności między mikroserwisami
  • procesy, które się zmieniły
  • ...

@technites_pl

Mechanika nawigacji

@technites_pl

@technites_pl

@technites_pl

@technites_pl

@technites_pl

@technites_pl

@technites_pl

@technites_pl

@technites_pl

@technites_pl

@technites_pl

@technites_pl

@technites_pl

Dokumentacja, która sama się pisze

By Marcin Markowski

Dokumentacja, która sama się pisze

  • 978