[ly000]

Pytanie do bardziej zaawansowanych programistycznych mirków. Co z reguły rozumiecie pod pojęciem dokumentacja techniczna? Dokumentacja techniczna to dość szeroki termin i może oznaczać wiele rzeczy, ale gdy ktoś wam każe zrobić dokumentację techniczną do skomplikowanego zadania nad którym pracowaliście 2 tygodnie i które właśnie skończyliście implementować, to co robicie? Jakiś pliczek markdown, który zawiera opis API, krótki opis działania oraz opis konfiguracji? Jakieś komentarze do najważniejszych elementów w kodzie? Krótki opis działania najważniejszych klas w formie komentarzy? Jak to u was wygląda? Chodzi o to, żeby osoby z zespołu mogły się z tym zaznajomić.
#programowanie #programista15k #oprogramowanie

[Saly]

@ly000: API powino być zawsze odukomentowane przy pomocy np. OpenAPI lub w komentarz jak to ma miejsce w gRPC. Jeśli chodzi o dokumentację to taki opis ogólny: po co, jak zostało zaimplementowane, jakie części systemu/serwisy są w użyciu, dlaczego tak a nie inaczej.

[Oo-oO]

@ly000: moim zdaniem opis api i konfiguracji to powinien być standard, komentarze w kodzie tam gdzie to konieczne (zgodnie z zasadą - "po co" a nie "co to robi"). Zależy też kto ma taką dokumentację otrzymać, jeśli to jakieś wewnętrzne narzędzie to inaczej jest traktowane niż rzecz idąca dla klienta, przykładowo jest mniej diagramów maszyn stanów, czy nie jest taka łopatologiczna. W skrócie napisz tak jak sam chciałbyś dostać opisany podobny

[E.....r]

@ly000: dokumentacja techniczna to coś czego nigdy nie ma xd

[czupek]

@ly000: HLD + linki do API, która ma OpenApi. Resztę da się wyczytać w kodzie.

[NoName4891]

@ly000: to chyba pytanie do juniorów. W robocie dbasz o to aby twojej roboty nikt nie przejął, sam ją robisz wolno, 10x wolniej niż taki frajer jak ty pytający o dokumentację, dbasz o to aby nigdy nie powstała. A w tym czasie robisz inne fuchy. I tak latami.

[ly000]

@NoName4891: ja mówię o normalnej firmie a nie jakimś januszeksie xD

[Oo-oO]

@NoName4891: kurła, smutne ale prawdziwe, połknąłem "zażudke" ;)