The mythical man-month  -  Dokumentace

Literatura:
Frederick P. Brooks, Jr. - "The mythical man-month"
Český překlad šesté kapitoly "Passing the Word" - Roman Skřivánek, 2002, úkol pro účely kursu APS na FEI VUT Brno

U velkých projektů vzniká problém s dorozumíváním mezi analytiky, kterých je úzká skupina a mezi implementátory, kterých je mnoho. Jak může skupina 10 architektů udržovat koncepční integritu systému, který buduje 1000 lidí? Taková technologie byla vypracována pro tvorbu designu System/360 a je rovnocenně použitelná i pro softwarové projekty.

Písemné specifikace
Manuál (nebo písemná specifikace) je nezbytný, i když ne jediný nástroj. Manuál je externí specifikací produktu. Předepisuje a popisuje každý detail toho, co uživatel uvidí a jako takový je nejdůležitějším produktem architekta.
Jeho vývojový cyklus se stále dokola upravuje tak, aby respektoval zpětnou vazbu od uživatelů a implementátorů, která ukazuje nedostatky výstavby a používání. Pro implementátory je důležité, že změny mohou být kvantovány, takže existují různé zobrazitelné datované verze.
Manuál nemá jen popisovat všechno to, co uživatel uvidí (včetně rozhraní); má se také zdržet popisu všeho, co neuvidí. To už je záležitost implementátora, jehož svoboda by při tvorbě neměla být omezována. Architekt musí být vždy připraven ukázat implementaci některého popisovaného rysu, ale nemá se snažit určovat způsob implementace.
Styl musí být precizní, úplný a musí vhodně popisovat podrobnosti. Uživatelé se často odkazují na jednoduché definice, přičemž každá z nich musí opakovat všechny základní věci a všechny přitom musí souhlasit. Manuály tak mají sklon být při čtení nudné a těžkopádné, ale precizní, což je však důležité.
Jednota knihy "System/360 Principles of Operation" pramení z faktu, že ji psali pouze dva lidé - Gerry Blaauw a Andris Padegs. Ideje pocházejí od přibližně deseti lidí, ale jejich přenesení do písemné podoby muselo být provedeno pouze jedním nebo dvěma z nich, měla-li být udržena konzistence literatury i produktu. Psaní definice vede nutně ke spoustě jednoduchých rozhodnutí, která nejsou vhodná k široké debatě. Příkladem v produktu System/360 je detail toho, jak má být po provedení každé operace nastaven Condition Code. Jednoduchý však není princip, který tato malá rozhodování činí všude konzistentní.
Myslím, že nejlepší ukázka psaní manuálu, kterou jsem kdy viděl, je příloha k "System/360 Principles of Operation" od Blauuwa. Ta pečlivě a opatrně popisuje hranice kompatibility System/360. Definule kompatibilitu, předepisuje to, jak jí má být dosaženo a vypočítává ty externí oblasti, ve kterých je architektura úmyslně mlčící, kde se výsupy jednoho modelu mohou lišit od výstupů jiných, kde se kopie daného modelu může lišit od jiného a kde se kopie může dokonce lišit od sebe samotné (po provedení konstrukčních změn). Toto je úroveň preciznosti, ke které směřují autoři manuálů, kteří tak musí opatrně definovat co je a co není předepsáno.

Formální definice
Angličtina, stejně jako kterýkoli jiný lidský jazyk, není samozřejmě přesným nástrojem pro takovéto definice. Proto musí k dosažení potřebné přesnosti autor manuálu namáhat sebe i svůj jazyk. Pro definice je přitažlivou alternativou použití formální notace. Koneckonců - přesnost je jistotou v obchodu, "raison d' être" formálních notací.
Vysvětleme nyní podstaty a slabiny formálních definic. Jak už bylo uvedeno, jsou formální definice precizní. Rozdíly jsou nápadnější, takže jsou dříve vyplněny. Co jim však chybí, je srozumitelnost. V anglické (nebo české, pozn. překladatele) literatuře mohou být ukázány principy struktur, struktura může být vykreslena ve stupních nebo úrovních a mohou v ní být ukázány příklady. Výjimky a kontrasty mohou být jednoduchým způsobem vyznačeny a zdůrazněny. A co je nejdůležitější, autor může vysvětlit, proč je něco tak či onak. Formální definice jsou vhodné potud, pokud jsou založeny na své eleganci a přesnosti. Aby byl však jejich obsah snadno pochopitelný a vhodný k výuce a ke studiu, vyžadují prozaická vysvětlení. Z tohoto důvodu si myslím, že se v budoucn!osti setkáme se specifikacemi, které se skládají jak z formálních definic, tak z definic prozaických.
Starobylé přísloví říká: "Níkdy nevyplouvej na moře se dvěma časoměřiči; vezmi si jeden, anebo tři." To stejné lze říci také o prozaických a formálních definicích. Má-li definice obě dvě části, musí být jedna z nich základní a druhá z ní odvozená; jako takové musí být označeny. Každá z nich může být definicí základní. Základní definicí jazyka Algol 68 je formální, zatímco odvozenou je definice prozaická. Základní definice PL/I je prozaická a odvozenou definice formální. System/360 má také základní prozaickou definici s odvozenou definicí formální.
Pro formální definice existuje mnoho nástrojů. Backus-Naurova forma je vhodná k definici jazyků a je bohatě popsána v literatuře. Formální popis PL/I používá nové pojmy abstraktní syntaxe a je vhodně vysvětlen. Iversonovo APL se používá k popisu strojů, například IBM 7090 a System/360.
Bell a Newell navrhli nové notace pro popis konfigurací i architektur strojů a ilustrovali je na několika systémech, včetně DEC PDP-8 a System/360.
Téměř všechny formální definice mají tendenci ztělesňovat a popisovat implementaci hardwarového nebo softwarového systému, jehož zevnějšky popisují. Syntaxi je možné popsat bez toho, ale sémantiky jsou obvykle definovány programem, který provádí definované operace. To už je ovšem implementace a jako taková přesahuje předpis architektury. Autor tedy musí být opatrný při indikaci toho, že se formální definice použije pouze na externality a musí říci, o které se jedná.
To, že formální definice je i implementací, platí i naopak - implementace může sloužit také jako formální definice. U prvních kompatibilních počítačů se jednalo právě o tuto techniku. Nový počítač se ztotožňoval s původním. Byl-li manuál v některých věcech vágní, bylo nejjednodušší vyzkoušet stroj. K určení chování se odkazoval testovací program a nový stroj byl konstruován ve shodě.
Podobným způsobem může stejně dobře posloužit programovatelný simulátor hardware nebo software - jedná se o implementaci a funguje. Všechny otázky ohledně definic mohou tedy být řešeny jeho testováním.
Použití implementace jako definice má několik výhod. Všechny otázky mohou být experimentem jednoznačně určeny. Není nutná debata, proto jsou odpovědi rychlé. Odpovědi jsou vždy tak precizní, jak je požadováno, a jsou podle definice korektní. Má však také několik hrozivých nedostatků. Implementace může předepisovat externality. I špatná syntaxe vždy poskytuje nějaký výsledek - v kontrolovaném systému je jím indikace neplatnosti a nic víc. V nekontrolovaném systému se mohou objevit všechny možné druhy postranních efektů, které mohou být použity programátory. Když se například rozhodneme emulovat IBM 1401 na System/360, objeví se 30 různých postranních efektů potencionálně možných neplatných operací, které se stanou obecně používané a budou chá!pány jako část definice. Implementace je jako definice příliš předepisující - není pouze řečeno, co má stroj dělat, ale také mnoho o tom, jak to dělá.
Dále také, jsou-li pokládány určité otázky, bude implementace občas dávat nečekané a neplánované odpovědi. Definice "de facto" bude v těchto podrobnostech shledána neelegantní. Tato neelegance se často ukáže drahá nebo pomalá pr duplikaci v jiné implementaci. Některé stroje například po provedení násobení zanechají v registrech činitelů nesmyslné hodnoty. Tato přirozenost se jeví jako součást definice "de facto", přesto může duplikace vyloučit použití rychlejšího algoritmu násobení.
Konečně je použití implementace jako formální definice zvláště podezřelé pro nejasnost, je-li základní definicí definice formální nebo prozaická. Je tomu tak zvláště při programovaných simulacích. Je nutné se zdržet modifikací implementaci, slouží-li jako standard.

Přímé vkládání
Pro architekty softwarových systémů existuje krásná technika šíření a vynucování definic. Je zvláště vhodná pro tvorbu syntaxe rozhraní mezi moduly bez sémantiky. Tato technika spočívá v konstrukci deklarace vkládaných parametrů nebo sdílené paměti a vyžadování implementací vkládání těchto definic prostřednictvím operací v době kompilace (makro nebo %INCLUDE v PL/I). Je-li navíc celé rozhraní odkazováno pouze symbolickými jmény, může být deklarace změněna pouhou rekompilací, bez jiných změn programu.

Rady a konference
Je zbytečné říkat, že schůze jsou nezbytné. Stovky malých konzultací musí být doplněny velkými a formálními shromážděními. Konají se na dvou úrovních - první je týdení konference všech architektů, trvající půl dne, druhou je oficiální reprezentace hardwarových a softwarových implementátorů a marketingu. Předsedou je vedoucí systémový architekt.
Kdokoli může navrhovat problémy nebo změny, návrhy jsou však obvykle doručovány písemně ještě před konferencí. Nový problém bývá nějakou dobu diskutován. Důraz není ani tak na samotném rozhodnutí, jako spíše na kreativitě. Skupina se pokouší mymyslet mnoho řešení problémů, poté je několik řešení svěřeno jednomu nebo několika architektům, aby je dále rozvedli do návrhů, přesně popsaných v písemné dokumentaci.
Podrobné návrhy změn potom přistupují ke schválení. Jsou postupně rozvažována implementátory a uživateli a připomínkovány. Je-li nalezen konsenzus, je to dobré. Není-li nalezen, rozhoduje vedoucí architekt. Je ušetřen čas a přitom jsou rozhodnutí široce, rychle a formálně rozšířena.
Rozhodnutí víkendových konferencí dávají rychlé výsledky a umožňují pokračovat v práci. Je-li někdo příliš nespokojen, jsou možná okamžitá odvolání k projektovému manažerovi, jsou však řídká.
Plody těchto shromáždění pramení z několika zdrojů:
1. Stejná skupina (architeki, uživatelé a implementátoři) se schází každý týden po několik měsíců. Není nutný čas ke svolávání v určitém čase.
2. Skupina je zřejmá, vynalézavá, zkušená a zaujatá na výsledku. Nikdo nemá pouze "poradní" funkci. Každý je schopen přebírat závazky.
3. Narostou-li problémy, jsou hledána řešení uvnitř i vně daných hranic.
4. Fromalita písemných návrhů zaměřuje pozornost, vynucuje řešení a potlačuje nekonzistence konceptů vzniklých při schůzi.
5. Propůjčení rozhodovací pravomoci vedoucímu architektovi potlačuje kompromisy a prodlevy.

V průběhu času se některá rozhodnutí vyčerpají. Některé vedlejší záležitosti nejsou zcela akceptována jednou nebo více stranami. Jiná rozhodnutí tvoří nečekané problémy a týdenní schůze je někdy nejsou schopny vyřešit. Tak se vytvoří zásoba měnšinových návrhů, otevřených výstupů a nedorozumění. Proto se držíme pravidelných nejvyšších schůzí, které typicky trvají dva týdny (při opakování každých šest měsíců).
Tyto schůze se svolávají před důležitými daty, významnými pro manuály. Nezahrnují pouze skupnu architektů a reprezentace programátorů a implementátorů, ale také řídící pracovníky programování a marketingu. Jsou řízeny projektovým  manažerem System/360. Agenda sestává typicky z asi 200 položek, většinou méně závažných, které jsou zobrazeny na přehledech v místnosti. Všechny strany naslouchají a činí rozhodnutí. Díky zpracování textu pomocí počítače (a činnosti mnoha dalších pracovníků) získá každý účastník další den novou verzi manuálů, ve kterých jsou zahrnuta včerejší rozhodnutí.
Tyto schůze jsou užitečné nejen pro revize rozhodnutí, ale i pro jejich akceptování. Každý lépe slyší, rozumí a podílí se na složitých tlacích a vztazích mezi rozhodnutími.

Paralelní implementace
Architekti System/360 měli dvě nepředvídatelné výhody: dostatek času k opatrné práci a stejné politické podmínky jako implementátoři. Dostatek času pochází z nových technogií; politická rovnost ze současné konstrukce paralelních implementací. Nezbytnost důsledné kompatibiliy je nejlepším způsobem tvorby specifikací.
U většiny počítačových projektů přijde den, kdy se zjistí, že stroj a manuál si neodpovídají. Když se tyto rozdíly prohlubují, manuál obvykle upadá, protože může být změněn rychleji a levněji než stroj. Tak tomu však není u paralelních implementací. Prodlevy a náklady spojené s opravou chybujícího stroje mohou být převýšeny náklady na revize strojů, které jsou konstruovány přesně podle manuálu.
Tato představa může být plodně použita, kdykoli je definován programovací jazyk. Existuje zde jistota, že několik interpretů nebo kompilátorů bude dříve či později muset být sestaveno tak, aby dosahovaly různých cílů. Definice bude čistší a disciplína pevnější, budou-li zpočátku budovány alespoň dvě implementace.

Záznam telefonátů
Jak implementace pokračuje, narůstají otázky o interpretaci architektury bez ohledu na to, jak přesná je specifikace. Mnoho takových otázek samozřejmě vyžaduje rozvedení v textu. Jiné pouze reflektují neporozumění.
Je důležité vést nejisté implementátory k tomu, aby telefonovali odpovědnému architektovi a pokládali mu své otázky, namísto toho, aby sami experimentovali. Je životně důležité pochopit, že odpovědi na takové otázky jsou prohlášeními architektů "ex cathedra" a musí být sděleny všem.
Použitelným mechanismem je záznam telefonátů, udržovaný architektem. V něm udržuje všechny odpovědi na všechny otázky. Každý víkend jsou záznamy několika architektů spojeny, reprodukovány a distribuovány všem uživatelům a implementátorům. Tento mechanismus je sice neformální, ale rychlý a obsažný.

Nezávislé testování
Nejlepším spojencem manažera je jeho každodenní protivník, nezávislá testovací organizace. Tato skupina kontroluje stroje a programy ve srovnání se specifikacemi a slouží jako "ďáblův advokát", přesně vytyčující každý myslůitelný defekt a rozpor. Každá vývojová organizace potřebuje k zachování své kvality takovouto technickou skupinu.
V poslední fázi je nezávislým auditorem zákazník. V nemilosrdném světle běžného používání se ukáží všechny kazy. Skupina testování produktu zastupuje zákazníka a specializuje se na hledání chyb. Čas od času najde pečlivý tester produktu místa, kde nebyl návrh správně pochopen, nebo dobře implementován. Proto je testovací skupina nezbytným článkem v řetězu, kterým je tvořen návrh, a který má pracovat současně s vývojem.