Zverejňovanie projektovej dokumentácie a integračných manuálov

Štát by mal v štandardizovanej forme zverejňovať API svojich informačných systémov. Ideálne centrálne.

Štandardom sa dnes stávajú služby ako apiary.io, getsandbox.com alebo readme.io.

2 Likes

Začul som tiež nápad zverejňovať projektovú dokumentáciu a taktiež detailnú funkčnú špecifikáciu. Vždy a minimálne v momentoch keď daná na akceptáciu zákazníkovi.

@Lubor, @gla ešte niečo k tomu vás napadá?

  • Autorské práva a know how je jeden argument prečo sa budú mnohé firmy brániť, preto je dôležité, aby bola táto požiadavka zahrnutá už v predmete obstarávania a kontrahovania. Dá sa to riešiť, ale je to pomerne dosť náročná operácia. EK principiálne pristupuje k tejto téme a dodávané metodiky a dokumenty sú zverejňované pod otvorenými licenciami. Pravdaže musia existovať výnimky, ale aj transparentný proces obhájenia výnimky.
  • Zverejnenie by malo byť neodkladné a malo by byť zverejnené ja to dokedy má zákazník šancu reagovať. Teda koľko času má na akceptáciu dokumentu - zväčša je to súčasť zmluvných nastavení. Aby mala verejnosť presnú informáciu dokedy je šanca do procesu zasiahnuť. Bolo dobré prezentovať hlavne pozitíva takejto participácie. V prvom rade by nemalo ísť o šliapanie po krku dodávateľovi, ale hlavne o prenesenie expertízy z odbornej komunity, ktorá sa dnes málo využíva.
  • Na to, aby sa projekty otvorili a zároveň aby nezabili už aj tak obmedzené kapacity úradníkov, je rozumné dodávať pripomienky verejnosti v konsolidovanej forme, čiže prispievajúce komunity by si mali konsolidovať svoje výstupy vrátane prioritizácie pripomienok. Na to by bolo dobré zjednocovať formu výstupu čo je kontinuálny proces vyladený so všetkými stranami.
  • Pripomienky verejnosti by zo začiatku nemali byt záväzné na prerokovanie. Aj takýto proces zlepšenia stavu projektov by mal získať svoju legitimitu. Po doladení procesu sa možno úradníci zhodnú, že je fajn zapracovať participáciu do procesu natvrdo. Ak nie, sami uvidíme do akej miery sa podarí koncentrovať verejný tlak v tejto téme.
  • Zároveň by bolo žiadúce, aby boli všetky pripomienky zverejnené rovnako ako dokumentácia vo zverejnenej dokumentácii k projektu (môže to robiť aj táto alebo obdobné iniciatívy pravdaže, bolo by fajn keby sa pripomienky stali ale oficiálne prílohy) a prípadné ignorovanie dôležitých faktov by malo byť počas životného cyklu projektu prehodnocované.
1 Like

potrebujeme ujasnit, co je rozsah “projektovej dokumentacie”. Je to strasne siroky pojem…

  • DFŠ
  • integračný manuál
  • používateľská príručka (aj keď podľa mňa to je antipattern)

@Lubor ma rad doplni.

za mna takto:

  1. Komplet ziadost o NFP s prilohami
  2. Zmluva o NFP (aj ked tie uz su na CRZ)
  3. Projektovy plan
  4. Plan kvality a kriteria kvality pre kazdy produkt
  5. DFS (alebo ekvivalent)
  6. Podklady k schvalovaniu platobnych milnikov (minimalne akceptacne protokoly k produktom)
  7. Register rizik

Integracny manual OK
Pouzivatelska prirucka sa uz dnes zverejnuje

2 Likes

Nielen to. Ak majú systémy vedieť rozumne spolupracovať, API treba silne riadiť / štandardizovať.
Niektoré oblasti, čo už snáď aj mali byť spravené:

  • el.formulár - napĺňacie funkcie (dotiahnutie údajov používateľa) a validačné funkcie - REST, Open API
  • podateľne - podanie, potvrdenie, stav overenia podania - Open API
  • údaje registrov - postaviť štandardizované API založené na ref.id., riešená autorizácia, platnosť+historické verzie, aktualizácia údajov - povinne rovnaké pre všetky registre, niečo k tomu som už písal
  • stav podania - od pridelenia čísla podania (nadväzuje na podateľňu), cez info. o konaní až po aktuálny stav+história - OpenAPI, časť údajov dostupná aj ako OpenData

V projektoch sú vytvárané mraky dokumentácie. Z nej by malo byť sprístupnené default všetko, vylúčiť kritické veci týkajúce sa bezpečnosti (podľa klasifikácie) a osobných údajov. Okamih zverejnenia default keď je dokument predložený na akceptáciu pre formálne schvaľované dokumenty, finálna verzia pre ostatné.

Typy dokumentácie:

  • manažérska dokumentácia - dokumentácia podľa prílohy č.4, pozri tam kap.7,
  • monitorovacia dokumentácia - reporty sú popísané tu, ale nemám v tom veľký prehľad
  • analytická dokumentácia - v projektoch je to robené rôzne, v zásade ide o katalóg požiadaviek, analýza stavu/procesov/legislatívy, DFŠ a iné špecifikácie, návrh riešenia a podobné
  • dokumentácia ktorá je súčasťou produktu - používateľská, administrátorská príručka, integračné manuály, metodiky, vzdelávacia dokumentácia
  • ekonomická dokumentácia - výkazy prác, fakturácie

Väčšina tohto všetkého je už dnes centrálne zhŕňaná do ASPR, treba tento systém otvoriť - je to úplne v kompetencii MF.

3 Likes

Myslim si, že je dobré ak zákazník dostáva dokumentáciu pred akceptáciou, aby sa mohol zúčastňovať na jej finalizácii. Tak sa súčasne overí, či je úplne zrozumiteľná a odpadnú budúce prekvapenia.