Předání softwarového projektu: dokumentace, přístupy a znalosti

Předání softwarového projektu se ve většině firem odehraje takto: přijde poslední faktura, k ní e-mail s odkazem na repozitář a věta, že všechno podstatné je v README. Tři týdny to funguje. Pak přijde první výpadek mimo pracovní dobu nebo požadavek na drobnou změnu — a ukáže se, že do produkční databáze vidí jediný člověk, který už u dodavatele nepracuje, doména je registrovaná na jeho soukromý účet a zálohy sice běží, jen je nikdo nikdy nezkusil obnovit.

Předání přitom není administrativní krok na konci. Je to samostatná fáze s vlastním rozsahem, harmonogramem, rozpočtem a akceptačními kritérii. A hlavně — dá se naplánovat od začátku projektu, nebo se dá improvizovat v posledním týdnu. Rozdíl mezi těmito dvěma přístupy zaplatí přebírající strana, zpravidla v nejhorší možnou chvíli.

Připravenost na předání není dokument, který se napíše na konci. Je to vlastnost projektu, která buď průběžně existuje, nebo neexistuje. Tým, který od začátku počítá s tím, že systém jednou převezme někdo jiný, pracuje jinak: infrastrukturu drží jako kód, ne jako sérii ručních kliků, tajemství ukládá do správce tajemství a ne do konfiguračních souborů na disku, účty třetích stran zakládá na firemní e-maily klienta a ne na osobní, a důvody architektonických rozhodnutí zapisuje tehdy, kdy rozhodnutí padne.

Ten poslední bod je rozhodující. Rekonstruovat osmnáct měsíců rozhodnutí v posledním týdnu projektu není dokumentace, ale archeologie — a výsledkem je text, který zní věrohodně a je z třetiny nepřesný. Pokud si během projektu procházíte jednotlivé fáze vývoje softwaru na míru, předání patří do plánu stejně jako testování nebo nasazení.

Druhá věc, která se řeší na začátku, je smlouva. Exitová doložka by měla pojmenovat, co přesně dodavatel při ukončení spolupráce předává, v jaké lhůtě, kdo je vlastníkem účtů a licencí a kolik hodin podpory je součástí ceny. Pokud se tohle řeší až ve chvíli, kdy je vztah napjatý, vyjednávací pozice klienta je slabá. Patří to mezi otázky, které má smysl položit už při výběru softwarového dodavatele.

Praktický checklist předání má tři okruhy. Nic z toho není exotické, a přesto se v reálných předáních pravidelně ztrácí minimálně polovina.

Kód, prostředí a nasazení

Repozitář včetně historie, ne pouze poslední snapshot. K němu popis větvení a release strategie — která větev je produkční, jak vzniká vydání, čím je označená verze, která právě běží v produkci. Dále seznam prostředí (vývoj, staging, produkce), čím se navzájem liší a kde ty rozdíly způsobují překvapení. A nakonec postup nasazení i postup návratu zpět. Rollback je ta část, která se dokumentuje nejméně často a potřebuje se nejnaléhavěji.

Přístupy, účty a licence

Klíčové slovo je rotace, ne sdílení. Předat přístup neznamená poslat existující heslo — znamená to vytvořit nové přihlašovací údaje pro přebírající stranu a staré zneplatnit. Totéž platí pro API klíče, servisní účty, SSH klíče a tokeny do CI. Dále sem patří účty poskytovatele infrastruktury včetně fakturačního vlastnictví, registrátor domény a správa DNS, účty třetích stran (platební brána, e-mailová a SMS brána, mapové a analytické služby, monitoring) a licence s daty obnovy. U mobilních aplikací navíc účty v obchodech s aplikacemi a podpisové certifikáty — bez nich se aplikace nedá aktualizovat, jen znovu vydat pod novou identitou.

Data, provoz a znalosti o systému

Schéma databáze a způsob, jakým se mění (migrace), retenční politika, a především procedura zálohování a obnovy. Zálohování se dá zkontrolovat za pět minut; obnova se musí vyzkoušet. Zálohu, kterou nikdo nikdy neobnovil, je třeba považovat za neexistující, dokud se neprokáže opak. Do tohoto okruhu dále patří monitoring a směrování alertů — po předání musí existovat jmenovitý člověk, kterému alert reálně pípne na telefonu. A nakonec záznamy architektonických rozhodnutí, seznam známých chyb i s obcházkami a runbook pro tři až pět nejčastějších incidentů.

Většina předávací dokumentace se píše v jednom nárazovém týdnu, předá se v PDF a od toho dne už jen zastarává. Po půl roce je nebezpečnější než její absence: tváří se jako zdroj pravdy, přičemž polovina postupů už neplatí, a člověk, který podle ní řeší incident, ztrácí čas ve slepé uličce.

Rozdíl mezi mrtvou a živou dokumentací není v kvalitě psaní, ale v tom, zda dokument někdo používá a zda se chyba projeví. Fungují tři typy obsahu. První je ten, který se nedá odvodit z kódu: proč bylo rozhodnutí přijato, jaké alternativy byly zvažovány, jaké obchodní pravidlo stojí za zvláštní výjimkou v objednávkovém procesu. Druhý je obsah, který se spouští — skript na lokální nastavení prostředí, který běží i v CI, seed dat, infrastruktura jako kód. Pokud přestane platit, pipeline spadne. Třetí je runbook, který se reálně otevírá při incidentech a po každém incidentu se upravuje.

Naopak dokumentace, která slovy převypravuje kód, je nepravdivá do několika týdnů. Dobrý test připravenosti je jednoduchý: nový vývojář dostane pouze dokumentaci, žádnou ústní pomoc, a má rozběhnout projekt lokálně a nasadit triviální změnu na staging. Co ho zastaví, to je díra v dokumentaci. Stejná logika platí i u dlouhodobé údržby a rozvoje softwaru po spuštění — dokumentace je provozní nástroj, ne příloha k faktuře.

Typický „knowledge transfer" vypadá jako série hovorů, kde dodavatel sdílí obrazovku a mluví. Přebírající tým přikyvuje, dělá si poznámky a odchází s pocitem, že rozumí. O měsíc později, při prvním skutečném nasazení, se ukáže, že nerozumí.

Funkční alternativa je obrátit role. Sezení jsou pracovní: klávesnici drží přebírající tým, dodavatel sedí vedle a odpovídá na otázky. Nasazení na staging dělá nový tým. Obnovu zálohy dělá nový tým. Simulovaný incident podle runbooku řeší nový tým. Tři až pět sezení po devadesáti minutách, každé s konkrétním výstupem, přinese více než dvacet hodin prezentací. Nahrávky sezení jsou užitečný doplněk, ne náhrada.

Znalost, kterou přebírající tým nikdy nepoužil vlastníma rukama, není přenesená — je jen nahraná na videu.

Zvláštní kategorií jsou znalosti o datech. U systému, který vznikl migrací ze starší platformy, bývá nejcennější informací to, které historické záznamy jsou nekonzistentní, proč a jak se s nimi zachází. Tato znalost je téměř vždy pouze v hlavách a téměř nikdy v repozitáři.

Mezi „dodavatel provozuje" a „dodavatel je pryč" patří přechodné období, typicky čtyři až osm týdnů podle složitosti systému. Nový tým provozuje, původní je v pohotovosti s dohodnutou reakční dobou a předem vyčleněným počtem hodin. Klíčové je zadefinovat, kdy se eskaluje: pokud nový tým volá při každé maličkosti, znalosti se nepřenesou, pokud nevolá nikdy, riskuje se výpadek.

Předání samo o sobě potřebuje akceptační kritéria — jinak nikdy nemá jasný konec. Rozumný soubor vypadá takto: přebírající tým samostatně nasadil změnu do produkce; samostatně provedl obnovu zálohy do testovacího prostředí; přihlásil se do všech účtů třetích stran a je jejich vlastníkem; alerty chodí jeho lidem; vyřešil alespoň jeden reálný nebo simulovaný incident bez zásahu dodavatele; a všechna tajemství byla rotována. Dokud tyto body neplatí, předání probíhá, ať už byla poslední faktura vystavena kdykoli.

Nejčastější příčina neúspěchu není na straně předávajícího. Je na straně přebírající: nikdo nemá na předání vyčleněný čas. Lidé jsou stoprocentně alokovaní na jinou práci, na sezení chodí „když stihnou", dokumentaci si přečtou později a později nikdy nepřijde. Výsledek je stejný, jako kdyby předání neproběhlo — s tím rozdílem, že obě strany si myslí, že proběhlo.

Prakticky to znamená tři věci. Jmenovitého vlastníka předání na přebírající straně, ne „IT oddělení". Reálnou kapacitu, orientačně dvacet až třicet procent času dvou až tří lidí během přechodného období. A jasně určeného člověka, kterému budou chodit alerty od prvního dne po ukončení pohotovosti. Pokud firma tyto tři věci nedokáže zajistit, je poctivější prodloužit spolupráci s původním dodavatelem než předat systém do prázdna.

Existuje i situace, kdy předání nedává smysl: systém je natolik propletený s know-how jednoho týmu a natolik málo zdokumentovaný, že jeho převzetí stojí více než přepsání kritické části. Tehdy je předání spíše řízeným útlumem než převzetím provozu. V INTERFASE takové situace řešíme v rámci vývoje softwaru na míru tak, že nejprve stabilizujeme provoz a teprve potom rozhodujeme o dalším osudu systému.

Předání softwarového projektu je proces, ne e-mail. Plánuje se od začátku, má vlastní rozsah a akceptační kritéria a končí tehdy, když přebírající tým systém samostatně nasadil, obnovil ze zálohy a přežil incident. Dokumentace má cenu jen tehdy, pokud se používá; přístupy se rotují, ne sdílejí; znalosti se přenášejí prací, ne prezentací. A ani dokonale připravené předání nefunguje, pokud přebírající strana nevyčlení jmenovitého vlastníka a reálný čas.

Pokud právě přebíráte systém po jiném dodavateli nebo připravujete předání svého projektu a chcete si projít checklist na konkrétním případu, ozvěte se nám — pomůžeme zadefinovat rozsah předání i jeho akceptační kritéria.