V procesu vývoje softwaru je často jedna věc, o které se hodně mluví – projektová dokumentace. Je nenahraditelná a je klíčem k procházení složitostí kódu. Zároveň je taky nutná k tomu, aby dobře fungovala spolupráce mezi členy týmu. V tomto blogu bych ráda připomněla problémy, které mohou vzniknout, pokud je dokumentace nedostatečná a vyzdvihnout pár důvodů, proč bychom ji měli udržovat.
Na úvod si ale řekněme, co to vlastně dokumentace je. Jedná se o sbírku všech manažerských a vývojových dokumentů a podkladů, které byly vytvořeny a použity během životního cyklu vývoje produktu.
To mohou být:
- Poznámky ze schůzek
- Projektový plán
- Testovací scénáře
- Roadmapa
Za sebe bych ještě přidala:
- Tickety a user storky v trekovacím systému – zápisy v ticketech, user storkách a popisy akceptačních kritérií mohou sloužit jako krásný vzor samostatné dokumentace nebo její součásti, pokud je máte srozumitelně napsané
- Testovací poznámky – výsledky z testování a poznámky, které se dělaly během nějakého složitějšího testování a automatizované testy
- Design – pokud je správně zpracován a jsou v něm komentáře s popisem stavu, který může nastat
- BE dokumentace – API dokumentace nebo datové struktury
- Samostatný kód
A to už je docela hodně, že? Teď si představte člověka, který na projektu pracuje a chce založit nebo už pracuje na existující dokumentaci. Typicky se pak může stát jeden z následujících scénářů.
Máme problém
Pokusí se sepsat všechno
Nejčastějším omylem je snaha zahrnout do dokumentace úplně všechno. Tento přístup u nás známý jako "přep*čenost", může způsobit ztrátu času a komplikovat přehlednost dokumentace.
Zanedbaná aktualizace
Starší projekty mohou trpět nedostatečnou aktualizací dokumentace. To pak vede k situaci, kdy dokumenty již neposkytují aktuální informace o projektu a vůbec nejsou k použití.
Nepřiřazení odpovědnosti
Nepřiřazení odpovědnosti za psaní a udržování dokumentace může vést k chaotickým výsledkům a nejasnostem.
Nepoužití jediného standartu psaní a špatná organizace dokumentů
To také souvisí s předchozím bodem, kdy máte určeno, kdo dokumentaci píše, ale každý v týmu to vnímá a dělá svým způsobem, což může přidat na chaosu a nejasnostech.
Proč chceme mít dobře udržovanou dokumentaci?
Pro lepší komunikaci a porozumění. Dokumentace usnadňuje komunikaci mezi vývojáři, testery, projekťáky a všemi, kteří pracují na projektu. Dobře udržovaná dokumentace pak zvyšuje šanci na úspěšnost projektu jako takového. Zároveň poskytuje historický záznam všech rozhodnutí, důvody proč se něco řešilo daným způsobem a zabraňuje opakování chyb. V případě záskoku nebo předání projektu někomu jinému je pak proces mnohem jednoduší, protože vždy máte jeden dokument, kam se můžete kouknout.
Správně zpracovaná dokumentace pomáhá s porozuměním jednotlivých features a jejich logiky, usnadňuje plánování a rozdělení priorit. Díky tomu, že před sebou máte neustále přesné požadavky, snadněji se vám hledají chyby, podle kterých testujete a jak už jsem zmínila v předchozím odstavci – je mnohem snažší práci někomu předat v případě záskoku nebo zapojení nových členů.
Jak řešíme dokumentaci v Ackee?
Na závěr bych se ještě ráda podělila o pár tipů, jak přistupujeme k dokumentaci my. Používáme standartní šablonu na QA a projektovou dokumentaci. Pro každý projekt máme takové overview v Redmine, ve kterém máme celý popis projektu a linky na všechna prostředí, podklady, seznam lidí, kteří na projektu pracují a kdy jsou důležité meetingy.
Pro menší projekty se snažíme vybrat maximálně 1-2 druhy dokumentace (nebo podle požadavků klienta) a stává se, že klidně můžeme mít design s komentářemi a user story. Dokumentaci tvoříme postupně během vývoje, abychom zachovali aktuálnost a minimalizovali zbytečnou práci.
Závěr
Dokumentace je nesmírně cenným nástrojem, pokud je udržována a aktualizována. Přináší jasnost, usnadňuje komunikaci a předávání znalostí a tím posiluje základy každého úspěšného projektu. Pojďme tedy všichni společně pracovat na tom, aby všechny naše dokumentace nejen existovaly, ale byly také neustále správně udržovány. Protože jenom tak je dokumentace přínosná.
