Dokumentace
k Java projektům

Jak psát s radostí skutečně udržovatelnou dokumentaci

Cíl: snížení nákladů na vývoj

Java
Maven

Asciidoc

PlantUML

Proč psát dokumentaci?

Refereční příručka - co, jak a proč děláme
"Domluvíme se a budeme si to pamatovat" je velmi naivní představa nezkušených vývojářů či manažera. Navíc, co když se časem obmění vývojový tým?
Každý vývojář snadno pochopí projekt jako celek a současně mu dáme možnost seznámit s relevantními implementačními detaily
Chápou-li vývojáři (analytici, programátoři, testeři) business myšlenku projektu, mají představu o konceptuálním datovém modelu a rozumí souvislostem mezi jednotlivými částmi systému, dokáží efektivněji implementovat nové funkce, předcházet duplikování již existující funkcionality, provést optimální refaktoring, ... to vše vede k udržovatelnějšímu, srozumitelnějšímu a čistčímu kódu především při moderním agilním vývoji. Rychlejší implementace nových a úpravy stávajících funkcí se pozitivně odráží ve finanční náročnosti projektu.
Výrazně urychlí zaučení nových vývojářů

Co je to udržovatelná dokumentace?

  • Dokumentace je neustále svázána s vlastním projektem
  • Existuje jediná ucelená dokumentace sdílená analytiky, programátory, testery a uživateli
  • Nedochází k duplikování informací (a nutné synchronizaci) v různých dokumentačních nástrojích (Javadoc, Wiki, ...)
  • Dokumentace je verzovaná (svn, git, ...)
  • Dokumentace se neustále vyvíjí, aktuální verze je vždy dostupná
  • Při zachování určitých konvencí je možné generovat ERD (Entity Relation Diagram) přímo z Java kódu
  • Dokumentaci lze generovat v různých výstupních formátech - HTML, PDF, ...

Jak psát udržovatelnou dokumentaci?

Dozvíte se v rámci prakticky zaměřeného školení, konkrétně:

  • Jak pomocí technologií Java, Maven, Asciidoc, PlantUML a dalších volně dostupných nástrojů psát skutečně udržovatelnou dokumentaci.
  • Co všechno a proč by kompletní dokumentace měla obsahovat a jak ji strukturovat.
  • Naučíme se nakonfigurovat jednotlivé nástroje, aby generování dokumentace probíhalo automatizovaně.
  • Pokusíme se nově získané poznatky aplikovat na Vaše firemní procesy / projekty.

Inspirace

  • Líbí se Vám dokumentace k frameworku Spring? Naučím Vás, jak si vytvořit stejně profesionální dokumentaci k Vašemu vlastnímu projektu a mnohem více.
  • Víte, že je možné vytvořit link z Javadoc dané třídy do konkrétní sekce v refereční příručce a opačně?
  • Chcete vložit úryvek kódu do referečního manuálu? Při úpravě kódu se updatuje i úryvek v manuálu.
  • Chcete v Javadoc třídy vidět relevantní část ERD (asociace na další objekty problémové domény, jejich popis a význam vazeb)?

 Další informace o školení