Účel

Dokument popisuje základní pravidla pro vedení a tvorbu dokumentace Sdíleného informačního systému TA ČR (dále jen „SISTA" nebo „projekt SISTA"). Dozvíte se z něj, jakým způsobem správně strukturovat, psát a spravovat dokumentaci k vaší službě či komponentě, aby byla v souladu se standardy SISTA.

Cílem je zajistit, aby veškeré příručky (např. HOWTO), definice API (OpenAPI) a další související specifikace byly snadno dostupné pro všechny participující týmy.

S pravidly pro vedení dokumentace souvisejí další samostatná pravidla:

Ú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 ekosystému spolupracujících služeb vyžaduje kvalitní a aktuální dokumentaci jednotlivých částí s cílem:

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

  • určit minimální standardy dokumentace při vývoji, údržbě a dalším rozvoji služeb,

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

  • určit dokumentační nástroje a procesy projektu SISTA a

  • udržet dokumentaci na srovnatelné kvalitativní úrovni bez ohledu na dev, který službu vyvíjel.

Přístup „Docs as Code"

Přístup „Docs as Code“ (dokumentace jako kód) je v projektu SISTA klíčovým principem, který zajišťuje, že dokumentace je verzována, udržována a spravována stejnými nástroji a postupy jako samotný zdrojový kód služeb (GitLab). Cílem je mít dokumentaci dobře dostupnou, snadno čitelnou a rozšiřitelnou.

Important
Důležité

  • Hlavním formátem pro psaní dokumentace je značkovací jazyk AsciiDoc. Výhodou tohoto formátu je jeho široká podpora napříč IDE a platformami s bohatými možnostmi generování výstupů do různých formátů (HTML, PDF, PDF/A, ODT a dalších).

  • Pro vizualizaci a tvorbu schémat se využívá přístup „diagram as code“ pomocí nástroje PlantUML, který umožňuje definovat UML a další diagramy čistě textovým zápisem.

Doporučené instrumentárium

Pro psaní dokumentace lze využívat editor AsciidocFX (vhodný pro začátečníky, neboť poskytuje živý náhled, navigaci v souborech a integraci s PlantUML a PDF exporty), pro pokročilejší uživatele jsou vhodné Visual Studio Code s nainstalovaným rozšířením pro AsciiDoc nebo JetBrains s AsciiDoc pluginem.

Rozšíření pro IDE obvykle velmi dobře podporují syntaxi, zobrazení živého náhledu a exporty např. do PDF. Zásadně se nedoporučuje přímé kopírování textů z MS Word.

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ě.

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. Vývojář, který zná strukturu dokumentace své vlastní služby, musí být schopen bez problémů a rychle dohledat potřebné informace i v dokumentaci k jakékoliv jiné službě v rámci projektu SISTA.

Tip
Tipy

  • Používejte krátké, jednoduché věty. Souvětí by nemělo mít víc než dvě věty. Vyhýbejte se dlouhým výčtům, rozsáhlým tabulkám, trpnému rodu, popisujte aktéry běžnou terminologií. 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 ř. XYZ“.

  • 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).

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

  • 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). Nové funkce 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

Dokumentace úzce spjatá se zdrojovým kódem musí být povinně uložena přímo v repozitáři služby na platformě GitLab.

Struktura složek a souborů je daná (. označuje kořenový adresář):

Název a umístění Obsah Formát

./README.md

  • Obsahuje základní „kartu služby“ (co služba dělá) ve formátu Markdown, která se zobrazuje v GitLabu a v Backstage

Markdown

./docs/HOWTO.adoc

  • Popisuje k čemu služba/komponenta slouží a jak se používá, dále obsahuje provozně technické informace spolu s popisem závislosti na dalších službách/komponentách.

AsciiDoc

./docs/DEVS.adoc

  • Popisuje v jakém jazyce a frameworku je služba vytvořená, z jakých služeb se skládá, jaká je organizace zdrojových kódů a jak se služba ze zdrojových kódů spouští (pro vývoj, test i produkci), klíčové třídy a názvové konvence.

AsciiDoc

./docs/API.yml

  • Obsahuje standardizovanou dokumentaci rozhraní služby. Jakmile je soubor správně nalinkován v konfiguraci pro Backstage a změny jsou nahrány do hlavní větve, automaticky se propíše do Katalogu služeb.

YAML

./backstage-configuration/

  • Slouží primárně k uložení konfiguračních souborů pro nástroj Backstage, který v projektu SISTA funguje jako Katalog služeb. Její nejdůležitější součástí je soubor catalog-info.yaml, který obsahuje veškerou potřebnou konfiguraci pro danou službu

YAML
Note
Poznámky

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

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

  • Dokumentace datových entit a používaných struktur musí být součástí datového katalogu.

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á.

Important
Důležité

  • 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“.

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. 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, + deployment.yaml

  4. 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
Note
Poznámky

  • Předcházející verze pravidel požadovala i existenci souboru OPS.adoc, který měl dokumentovat službu pro potřeby OPS týmu. Od tohoto souboru upouštíme, protože vše potřebné musí být popsáno v deployment descriptoru a odchylky by neměly být možné.

Závěr

Soubor pravidel architektury, vývoje a vedení dokumentace představuje mantinely pro Dev týmy, přičemž účastníci rámcové dohody jsou povinni tato pravidla dodržovat. Zároveň také platí, že zadavatel podporuje jejich průběžnou aktualizaci a to dle závěrů Archa rady, z úrovně řízení projektu či dobré praxe.

Tip
Tip

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 (srov. s 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 (srov. s 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.

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

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

01

Šablony dokumentace uložené v repozitáři service-template

02