Úvod

Záměrem TA ČR je vybudovat a provozovat SISTA jako cloud native systém. Takový systém má být odolný, snadno kontrolovatelný, robustní a nezávislý na konkrétních dodavatelích technologií. Základní architektonické uspořádání SISTA jako množiny spolupracujících služeb vyžaduje kvalitní a aktuální dokumentaci jednotlivých částí.

Tento dokument nastavuje pravidla pro dokumentaci služeb v rámci SISTA a formu spolupráce mezi TA ČR a dodavateli i dodavateli mezi sebou.

Cílem je:

  • jednoduchý a obecně srozumitelný popis chování a řízení služeb,

  • určení minimálních standardů dokumentace při vývoji, údržbě a dalším rozvoji softwaru,

  • stanovení způsobu tvorby a dlouhodobého udržování aktuální dokumentace,

  • určení sdílených dokumentačních nástrojů a postupů v rámci TA ČR a

  • vzájemné pochopení a spolupráce všech týmů.

V průběhu řešení projektu „Sdílený informační systém TA ČR” očekáváme pravidelnou aktualizaci pravidel dokumentace dle potřeb dev i ops týmů.

1. Základní požadavky na dokumentaci

Základní požadavky na dokumentaci vyvíjené služby lze shrnout do tří pravidel – dokumentace musí být:

  1. dobře dostupná,

  2. dobře čitelná,

  3. snadno rozšiřitelná.

Jakákoli dokumentace je lepší než nic. Zdrojové kódy ani další artefakty v repozitářích nikdy nebudou obsahovat všechny informace – vždy budou existovat

  • konfigurační parametry, které je třeba nastavit,

  • speciální funkce, implementované kvůli výjimkám objeveným v ostrém provozu,

  • nutná ošetření historických dat, jež nelze z legislativních důvodů smazat a podobně.

Preferovaným jazykem dokumentace je čeština (vč. komentářů ve zdrojovém kódu).

1.1. Dobře dostupná dokumentace

Dokumentace musí být snadno dohledatelná – buď ve sdíleném úložišti pro všechny služby, nebo podle sdíleného schématu pro specifickou dokumentaci. Na každou službu má být možné uplatnit jednoduché kritérium: každý dodavatel, který se orientuje ve své službě, by měl umět najít potřebné informace v dokumentaci kteréhokoli další služby.

Vyžadovaná struktura ve sdíleném úložišti je popsána níže.

Note
Doporučení

  • Používejte krátké, jednoduché věty. Souvětí by nemělo mít víc než dvě věty. Vyhýbejte se trpnému rodu, popisujte aktéry běžnou terminologií. Vyhýbejte se dlouhým výčtům a rozsáhlým tabulkám. Obrázky by také měly být jednoduché.

  • Příklad: „služba ABC dělá XYZ, potřebuje to a ono“, „k vytvoření reportu musí mít uživatel příslušná práva“, „proměnnou ENV je třeba nastavit v konfiguraci služby na ř. 666“.

Kde je to účelné, dokumentujte pomocí obrázků a schémat – obrázek vydá za tisíc slov. Doporučené jsou textové formáty — AsciiDoc + PlantUML, příp. obdobné systémy tvorby obrázků z textu (swimlanes.io apod.).

Totéž se týká tabulek, pokud je tabulka malá a přehledná (max. 5 sloupců a jednoslovný nebo max. několikaslovný obsah jednotlivých buněk).

Používejte odkazování prostřednictvím hyperlinků. To se týká jak různých částí dokumentace, tak např. dřívějších verzí nebo odkazů na konkrétní komity v repozitáři.

Pro speciální případy (např. architektonická rozhodnutí) použijte oborový standard, existuje-li (např. XML Metadata Interchange). V případě nejasností ohledně nástrojů konzultujte tým TA ČR.

1.2. Snadno rozšiřitelná dokumentace

Dokumentaci musí být možné snadno v budoucnu měnit a doplňovat, proto pravidla vyžadují použití textových formátů (Markdown, AsciiDoc). Přidání nových funkcí musí být snadné doplnit do administrátorské i uživatelské příručky. Změny v chování musí být možné jednoduše popsat. Změny musí zahrnout i označování zastaralých pasáží a mazání / verzování již nepotřebných informací.

Note
Doporučení

  • Využijte verzovacích vlastností sdíleného repozitáře (Gitlab). Odkazujte na dřívější revize kódu i dokumentace, kde to má smysl. Př.: „ověření uživatele je od verze 6c5703d možné pouze prostřednictvím NIA a Google“, „dokumentaci pro verzi 4f644a1 a starší je nutné získat v dřívější verzi“.

1.3. Umístění dokumentace

Všechna dokumentace se musí nacházet nanejvýš na třech místech:

  • pokud jde o chování kódu, konfiguraci, dokumentaci API – obecně záležitosti úzce spjaté se zdrojovým kódem – má být dokumentace součástí repozitáře (Gitlab), viz též návod v dokumentu HOWTO Platform,

  • obecně sdílené vlastnosti (př.: zálohování, ops dokumentace, uživatelská příručka) mají být pro všechny služby na jednom místě,

  • dokumentace datových entit a používaných struktur musí být součástí datového katalogu, viz [MT039].

1.3.1. Struktura souborů v repozitáři

Požadovaná struktura dokumentace v repozitáři je následující (. označuje kořenový adresář, tučně jsou vyznačené povinné položky):

Název, umístění souboru Obsah Formát (k zobrazení v)

./README.md

Karta služby: základní popis, co služba dělá

Markdown (Gitlab, Backstage)

./docs/HOWTO.adoc

Informace pro volající stranu (vývojáři ostatních TRSů) – použití, pořadí volání, na co dávat pozoz

AsciiDoc (PDF odkaz v Backstage)

./docs/DEVS.adoc

Informace pro vývojáře (rozvoj / převzetí služby) – struktura kódu, architektura, použité knihovny, frameworky

AsciiDoc (PDF v Backstage)

./docs/OPS.adoc

Informace pro ops nad rámec základní dokumentace v Backstage – vysvětlení, kde nestačí komentář v příslušném konfiguračním souboru

AsciiDoc (PDF odkaz v Backstage)

Vzorové dokumenty jsou obsaženy v repozitáři service-template ve složce docs/.

Note

PDF soubory není nutné tvořit ručně, Gitlab zobrazuje formát AsciiDoc přímo.

2. Dokumentace sdílená pro všechny služby SISTA

Sdílená dokumentace pro všechny služby SISTA je uložena na společném úložišti: Rozcestník dokumentace SISTA, které mj. obsahuje strukturované informace o:

  • základní architektuře,

  • nasazení,

  • spuštění, zastavení – na obecné úrovni v rámci kontejnerového prostředí (př. kubectl start XYZ …),

  • ověření běžných scénářů, základní troubleshooting,

  • obnova ze zálohy, zálohování – pokud se postup odlišuje od obecného rámce SISTA,

  • uživatelská dokumentace – příp. různé typy uživatelské dokumentace (př. příručka pro hodnotitele se liší od příručky pro řešitele projektu, resortního správce atp.),

  • knowledge base – údržba, evidence incidentů,

  • FAQ – časté dotazy ad.

Forma dokumentace je celou SISTu stejná.

Sdílená dokumentace je maximálně otevřená, tj. pouze citlivé údaje (přístupové kódy, bezpečnostní prvky) jsou pro neoprávněné uživatele skryté. Výchozí nastavení je „všichni mohou vidět všechno“.

Pro potřeby koncových uživatelů je vhodné poskytnout dokumentaci ve formě neměnného dokumentu (PDF). Takový dokument se má pravidelně generovat ze sdíleného úložiště a pro koncové uživatele být dostupný pod generickým odkazem, nezávislým na konkrétní revizi dokumentu.

Note

Automatické generování PDF dokumentů ze sdíleného úložiště zatím nefunguje, dokumentaci je nutné vytvořit ručně.

3. Dokumentace specifická pro konkrétní službu

Specifická dokumentace by měla obsahovat všechny následující části, které dávají pro danou službu smysl. Připojený štítek Doporučené umístění ukazuje doporučené umístění dané části dokumentace dle navržené struktury v kap. 1.

  1. Základní popis služby – jednoduše, srozumitelně popsané chování a fungování služby – základní „karta služby“, která se používá do zadávací dokumentace pro navazující minitendry.

    Povinné umístění: README.md (Gitlab, Katalog služeb)

  2. Popis využití služby:

    • co služba dělá, proč to dělá, případně jak to dělá, pokud je možností více a chování závisí na vnějších okolnostech,

    • co další služba používá, kam se připojuje – týká se jak ostatních služeb SISTy, tak příp. služeb 3. stran,

    • kam služba posílá jaká data a proč.

    • dokumentace API – v prostředí SISTA se jedná o nejdůležitější rozhraní mezi službami:

      1. OpenAPI (Swagger) – formalizovaný popis veřejně dostupných funkcí API se standardizovanou syntaxí (součást živého Katalogu služeb), vč. datových struktur – viz HOWTO Platform,

      2. jak má volající služba pracovat s datovými entitami (typicky operace typu CRUD) – zejména v případech, kdy práce s daty vyžaduje speciální postup(y),

      3. validační pravidla, jsou-li nastavena.

    • datové toky, nejsou-li zřejmé z dokumentace API:

      1. pokud je to vhodné (což je často), nechť jsou datové toky součástí dokumentace API spolu s detaily interakcí (např. pořadí volání end-pointů apod.),

      2. zda jsou volané další služby, které a jaké datové entity jimi poskytované daná služba využívá,

    • dokumentace zpráv rozesílaných prostřednictvím fronty zpráv.

      Doporučené umístění: HOWTO.adoc + živá dokumentace dostupná z Katalogu služeb

  3. Provozní informace – kde se nacházejí potřebné zdroje, pokud nestačí základní popis pro platformu:

    • struktura větví v repozitáři, která větev je která (produkce, vývoj, testy) – pokud je použité nějaké neobvyklé schéma, pak též vysvětlení postupu přebírání / probublávání změn – např. jakou cestou se oprava dostane až do produkce,

    • adresy – URL jednotlivých verzí (produkce, test, …)

    • příp. IP adresy, porty a další konkrétní technické informace, pokud je to třeba (loadbalancing atp.).

      Doporučené umístění: Katalog služeb + OPS.adoc

  4. Konfigurační údaje – co všechno služba potřebuje nastavit, aby bylo možné ji spustit v žádaném prostředí, pokud nestačí základní popis pro platformu:

    • konfigurační parametry pro kontejnerizaci – co předat zvenku, ready / health checky,

    • konfigurace prostředí – DB, URL / IP adresy + parametry volaných služeb, vč. jejich umístění – konfigurační soubory, proměnné prostředí atd.,

    • popis jednotlivých parametrů – změny chování, balancing atp.,

    • odlišnosti pro jednotlivá prostředí (vývoj, test, produkce), jsou-li,

    • úpravy konfigurace operačního systému, pokud jsou potřeba – specifické pro danou službu, nemyslí se obecná úprava /etc/hosts.

      Doporučené umístění: Katalog služeb + OPS.adoc

  5. Deployment, spouštění, zastavování, troubleshooting – základní operace s službou pro ops tým, pokud nestačí základní popis pro platformu:

    • spuštění služby pro různá prostředí– vývoj, test, produkce + ověření, že spuštění proběhlo korektně,

    • zastavení – samostatně nebo prostřednictvím kontejneru, postupy a jejich dopady, pokud se liší,

    • typické chybové stavy a jejich projevy („nelze se připojit k DB“, „neběží služba XYZ“) – jakým způsobem lze chyby řešit,

    • základní sémantika logů – co hledat v logu, když …,

    • struktura auditních záznamů (co vše se audituje a za jakých okolností).

      Doporučené umístění: Katalog služeb + OPS.adoc

  6. Podrobnosti implementace služby:

    • odkaz na původní požadavky, vč. scénářů užití, byly-li připraveny,

    • použité jazyky, frameworky, knihovny vlastní i 3. stran,

    • organizace / struktura zdrojových kódů:

      1. backend / frontend – generování klientského kódu, metaprogramování atd.,

      2. MVC nebo jiné paradigma,

      3. odkaz na doporučené / pro daný jazyk typické uspořádání kódu, existuje-li,

    • zabezpečení, autentizace, autorizace – přístupové údaje, tokeny, klíče, certifikáty, jsou-li třeba; pokud se jedná o citlivé údaje, dokumentace je nesmí přímo obsahovat,

    • klíčové třídy, jmenné konvence,

    • hlavní použité koncepty:

      1. závisí na konkrétní službě,

      2. co dělá, proč takto; schéma, příp. datový model nebo odkaz na něj,

      3. popis důležitého algoritmu („když uživatel 3× zadá špatně heslo, stane se A, pak B, pak C…“),

    • dokumentace architektonických rozhodnutí (architecture decision records), která jsou za konkrétním kódem

      1. může se týkat použitých nástrojů, knihoven, přes organizaci zdrojových kódů, implementaci algoritmů až po předpoklady, které služba dělá za uživatele,

      2. př.: „proč jsme vybrali knihovnu XYZ“, „proč jsou testy v adresáři FFF“, „proč jsme implementovali vlastní SAML handshake“, „proč vyžadujeme, aby uživatel měl roli ABC“,

      3. konkrétní realizace může být různá:

        1. komentář ve zdrojovém kódu – důležitá je srozumitelnost komentáře,

        2. popis komitu do repozitáře,

        3. textový soubor v repozitáři při komitu současně se zdrojovým kódem – např. v dedikovaném adresáři decisions/,

        4. poznámka / wiki stránka / odrážka ve sdílené dokumentaci + odkaz na ni ve výše uvedeném komentáři / komitu / …,

    • datový model:

      1. základní struktura („in-memory řešení“, „key-value databáze“, „normalizovaná relační DB“, …),

      2. přehled základních datových struktur – cílem není pojmenovávat položky číselníku, ale poskytnout rychlou orientaci nad použitými strukturami,

      3. odkaz na příslušné položky datového katalogu, viz kap. 2.2. Práce s Datovým katalogem v [MT039], vč. dalších informací (primární zdroj, kopie atd.),

      4. implementační detaily, jsou-li – uložené procedury, constrainty / povinné vazby, validační pravidla atp.,

      5. pokud to úložiště umožňuje, mělo by obsahovat komentáře popisující definované datové entity, aby byla jejich funkce pochopitelná přímo z definičního schématu,

      6. výkonnostní požadavky na DB, jsou-li třeba – min. velikost RAM, dostupný diskový prostor, vlastnosti replikace / škálování atd.,

      7. záloha & obnova dat ze zálohy (migrační postup, je-li třeba).

        Doporučené umístění: DEVS.adoc

4. Nástroje pro dokumentaci

Kromě oprávněných případů, kdy takové použití není možné, se k dokumentaci služby vyžaduje formát AsciiDoc v kombinaci s dalšími popisnými jazyky (PlantUML, Mermaid).

Doporučené nástroje pro práci s těmito formáty:

Pro dokumentaci dalších skutečností (např. architektura, kontext služby, stavový diagram) dodavatel zvolí vhodný formát dle zkušeností, příp. konzultuje vhodné nástroje s ops týmem.

Ukázka Aplikace AsciiDocFX
Figure 1. Ukázka Aplikace AsciiDocFX

5. Zatím nezařazené

  • knihovny 3. stran – zálohovat nějakou bezpečnou archivní verzi ve vlastním repozitáři?

  • instalace – má se hypoteticky předpokládat, že by se něco instalovalo jinak než deployem v kubernetes? možná pro nějaké potřebné podpůrné systémy typu RabbitMQ? nebo odkázat na ops dokumentaci dodanou týmem TA ČR?

  • napojení na monitoring – bude nějaký Zabbix?

  • generování dokumentace by mělo být pokryté nějakým druhem testu – pokud generování selže (př.: špatná verze nástroje, syntaktická chyba atd.), má se zodpovědná osoba dozvědět, že se něco nepovedlo

6. Release notes dokumentu

Verze: 1.5.1.
Datum vydání: 31. 1. 2024.
Autor: David Ondřich (fnx.io), dond@dond.cz.
Poznámka k verzi: Přesun šablon do repozitáře service-template.

Detailní popis změn:

  • Vytvoření obsahu a základní kostry pravidel vedení dokumentace na základě zrušeného MT023.

  • Aktualizovaná verze, zahrnující doporučení minitendru pro data governance (MT039).

  • Doplnění vyžadované struktury dokumentace služeb a vzorových šablon.

  • Test plány.

  • Přesun šablon do repozitáře service-template.

Termíny a definice

API

programové aplikační rozhraní; zde synonymum pro REST API

Datová entita

Datová reprezentace reálného objektu v datovém modelu, představující daný typ objektu. Příklad: uživatel, projekt, zakázka.

Datová položka

Záznam v datovém slovníku, popisující reálně používanou datovou entitu a/nebo strukturu, viz analytickou zprávu [MT039].

Datový slovník

Data Dictionary, souborný přehled popisu reprezentace a správného použití definovaných datových entit, viz analytickou zprávu [MT039].

DevOps

Složenina anglických výrazů Development a Operations. Je to přístup k vývoji software, který zdůrazňuje komunikaci, spolupráci a integraci mezi vývojářem a odborníky na informační technologie z provozu.

Dev tým

Tým vývojářů, inženýrů, testerů a dalších potřebných rolí dodavatele.

Git

distribuovaný verzovací systém; též repozitář, Gitlab

MQ

message queue, (asynchronní) fronta zpráv; sdílený zdroj informací o událostech v jednotlivých službách

Ops tým

Tým vývojářů, správců, testerů a poučených uživatelů TA ČR.

AsciiDoc

Značkovací jazyk pro přípravu textů. Zároveň jde o multiplatformní program napsaný v Pythonu. AsciiDoc formát vznikl již v roce 2002 a následně byl v roce 2013 uvolněn klon - AsciiDoctor napsaný v Ruby a používaný mj. na GitHubu.

Odkazy a zdroje

Vnitřní předpisy a dokumenty
Regulatorní požadavky

  • [ZPVV] ČESKO. Zákon č. 130/2002 Sb., o podpoře výzkumu a vývoje z veřejných prostředků a o změně některých souvisejících zákonů (zákon o podpoře výzkumu a vývoje). In: Zákony pro lidi.cz [online]. © AION CS 2010-2022 [cit. 6. 1. 2022]. Dostupné z: https://www.zakonyprolidi.cz/cs/2002-130

  • [ZZVZ] ČESKO. Zákon č. 134/2016 Sb., o zadávání veřejných zakázek. In: Zákony pro lidi.cz [online]. © AION CS 2010-2022 [cit. 6. 1. 2022]. Dostupné z: https://www.zakonyprolidi.cz/cs/2016-134

  • [ZISVS] ČESKO. Zákon č. 365/2000 Sb., o informačních systémech veřejné správy a o změně některých dalších zákonů. In: Zákony pro lidi.cz [online]. © AION CS 2010-2022 [cit. 6. 1. 2022]. Dostupné z: https://www.zakonyprolidi.cz/cs/2000-365

  • [VYVIS] ČESKO. Vyhláška č. 317/2014 Sb., o významných informačních systémech a jejich určujících kritériích. In: Zákony pro lidi.cz [online]. © AION CS 2010-2022 [cit. 6. 1. 2022]. Dostupné z: https://www.zakonyprolidi.cz/cs/2014-317

Internetové zdroje

Rejstřík

Příloha A: Šablony a formuláře

ID Název přílohy s odkazem repozitář Verze

01

šablony dokumentace

leden 2024

02

03

04

05

06

07

08

09

10