C3V14.pdf

Type: Document | Status: ready
← All sources

Metodika pro psaní článků určených k publikaci

Vytvořeno v rámci projektu

Rozvoj datových politik v oblasti zlepšování kvality a interoperability dat veřejné správy CZ.03.4.74/0.0/0.0/15_025/0013983

Klíčová aktivita: 04 Návrhy a realizace opatření pro zvyšování povědomí o otevřených datech Indikátor: 8 05 00 Počet napsaných a zveřejněných analytických a strategických dokumentů (vč. evaluačních)

Verze výstupu: 01

Obsah

Obecný cíl článků 3 Datový článek (projektový indikátor) 3 Parametry datových článků 3 Datový článek obsahuje tyto sekce: 3 Propagační článek 4 Parametry propagačních článků 4 Propagační článek má doporučené tyto sekce: 4 Proces psaní článku: 4 Technická část metodiky psaní článků - praktické pokyny pro autory 5 Předávání textů k publikaci na webu 5 Proces odevzdání článku 5 Technická stránka: Pro zdatné s GitHubem apod. 6 Technická stránka: Pro… méně zdatné 6 Formát a nástroje pro psaní textů 6 Nadpisy 6 Anotace 7 Odkazy 7 Offline citace 8 Tabulky 8 Obrázky 9 Hlavička (Front matter) 10 Externí aplikace a projektová publicita 11

Obecný cíl článků Články jsou jednou z možností, jak sdělovat informace a znalosti cílovým skupinám otevřených dat. V zásadě existují dva typy článků, které v rámci KODI publikujeme. Jedná se o “datové články” a dále o “články propagační”. Cílem metodiky je poskytnout autorům článků souhrnný postup pro přípravu a publikaci článku.
Datový článek (projektový indikátor) Datový článek představuje nový obsah POD pro širokou (informatickou) veřejnost v podobě článků a interaktivních vizualizací s využitím otevřených dat katalogizovaných v NKOD. Články a interaktivní vizualizace mají proto dva účely:

  1. informační - informování o otevřených datech a hodnotě v nich ukryté
  2. vzdělávací - ke každému článku a vizualizaci bude zveřejněn též detailní popis způsobu, jakým byl článek či vizualizace vytvořena (technologie, nástroje, postupy).

Parametry datových článků

Cílová skupina: široká veřejnost, články je tedy třeba psát popularizačně naučnou formou Použitá data: datové sady využité pro zpracování vizualizace nebo aplikace, která je v článku diskutována, musí být registrována v NKOD Rozsah textu: rozsah jednoho článku by měl být min. 1 strana A4, max. 5 stran A4 Vzdělávací obsah: v rámci textu by mělo být popsáno, jak byla data zpracována, aby vypadala tak, jak je to uvedeno v článku (nástroje, postupy, technologie) Vizualizace: může být statická nebo dynamická

Datový článek obsahuje tyto sekce:

  1. Povinně: “Název” - název článku

  2. Povinně: “Úvod” - zde bude popsáno, o co v článku jde a k čemu to slouží - max 2 věty + ideálně screenshot vizualizace viz bod č. 3. Technicky se tato část nazývá Anotace viz níže v textu.

  3. Nepovinně: “Výsledek” - prezentace toho, k čemu se v rámci článku chceme dostat

  4. Povinně: “Použitá data” - zde budou popsány jednotlivé datové sady, co byly použity v rámci článku z NKOD nebo ED případně z jiných zdrojů

  5. Povinně: “Postup zpracování” - zde bude popsáno, jak je nutné publikovaná otevřená data zpracovat, aby bylo možné dosáhnout chtěného výsledku - jako první bude subsekce “Instalace potřebných programů”, pokud to bude potřeba

  6. Povinně: “Výsledek” - prezentace finálního výsledku článku

  7. Povinně: “Další užití” - informace o dalších možných datových sadách, které lze takto zobrazit/vizualizovat/vložit do aplikace + informace o dalším typu užití této formy zpracování otevřených dat + případné srovnání publikace obdobných dat v dalších zemích (EU)

  8. Povinně: “Použité ná stroje a zdroje” - seznam použitých nástrojů, které byly pro zpracování použity včetně informace o jejich dostupnosti (číselník: 1.open source aplikace 2. aplikace dostupná zdarma. 3. Služba zdarma po registraci 4. placená služba) + Uvedení zdrojů na zajímavé doplňkové texty (nejedná se o seznam použitých zdrojů pro tvorbu článku)

  9. Povinně: “Autor” - informace o autorovi a případně odkaz na jeho github/LinkedIn (Pokud článek dostanete až do githubu, místo této sekce uveďte údaje dle metodiky JaKl v sekci “hlavička”)

Propagační článek Propagační článek není projektovým indikátorem, je však významnou součástí projektového cílu 3 - Zvyšování povědomí o otevřených dat. Tyto články jsou určené především k publikaci v externích médiích, kde je domluvena spolupráce - časopisy eGovernment, Moderní obec, Obec&Finance aj. (ale samozřejmě v případě potřeby je publikujeme i na POD).
Propagační článek nemusí obsahovat interaktivní vizualizaci na otevřených datech katalogizovaných v NKOD. Články mají také dvojí účel:

  1. informační - informování nejčastěji o novinkách v tématu otevřených datech
  2. vzdělávací - tyto informace lze v obecné rovině také využít pro vzdělávání dané osoby, ale zejména v koncepční, než už tak technologické rovině.

Parametry propagačních článků

Cílová skupina: široká veřejnost -> psát to popularizačně naučnou formou Informační část textu: Rozsah jednoho článku by měl být cca 1-3 strany A4, dle požadavků redakce příslušného média

Propagační článek má doporučené tyto sekce:1

  1. popis tématu článku (o co v článku jde) s cílem téma popsa t tak, aby bylo zjevné, proč je článek důležitý pro rozvoj ekosystému otevřených dat
  2. souvislost tématu s “otevřenými daty ” - popis jak souvisí otevřená data s daným tématem článku a jak byly případně použity otevřená data z NKOD nebo ED pro téma článku
  3. text samotného článku
  4. zdroje
  5. Autor + loga a číslo projektu

Proces psaní článku:

  1. Výběr tématu a termínu odevzdání článku je třeba potvrdit s pověřeným pracovníkem koordinujícím proces publikace článků.
  2. V první fázi je třeba článek vložit jen jako text do připravené složky na KODI Google Drive (složky jsou v pracovním adresáři příslušného projektového výstupu), následně proběhne obsahová a jazyková kontrola. V této fázi je případně možné vložit do textu i náhledy obrázků, aby recenzenti z OHA získali představu o podobě článku.
  3. Po zapracování případných změn na drivu následuje standardní proces publikace přes github - tzn. nahrání článku do připravené feature branche. Následuje technická kontrola, kterou provede pověřený pracovník. Technické zpracování článku musí být v souladu s technickou stránkou této metodiky dle kapitoly Formát a nástroje pro psaní textů včetně procesu odevzdávání a psaní, proto věnujte pozornost také kapitole Předávání textů k publikaci na webu.

1 Pořadí není závazné jako u datových článků, i když je doporučováno.

Technická část metodiky psaní článků - praktické pokyny pro autory Budou vznikat různé texty, které nejprve vyjdou na webu data.gov.cz, následně mohou být přebírány do dalších médií. To znamená, že jednotlivé texty bude potřeba přenášet mezi různými médii a jim určenými formáty. Hlavní překážkou tomuto procesu bývá “lidová tvořivost” zejména co se týče vizuálního formátování vzniklých textů, čemuž napomáhá používání textových editorů typu Google Docs, nebo nedejbože MS Word. Tomu se snažíme zabránit a vyhýbat - striktně oddělujeme obsah textu od jeho vizuálního formátování.

Při tvorbě textů nám tedy půjde výhradně o textový obsah, případně význam typu “nadpis třetí úrovně”, “kus kódu” nebo “číslovaný seznam”. Zakázané je bezvýznamové, vizuální formátování typu “kurzíva”, “tučně”, “větší nadpis”, “menší nadpis”, barvičky, fonty, poznámky pod čarou, apod. Usnadníme tím převody mezi různými formáty - na web, pro tisk a práci na textech v GitHubu. Předávání textů k publikaci na webu Proces odevzdání článku

  1. Nejprve je třeba připravit text v souladu s kapitolou Formát a nástroje pro psaní textů.

  2. Pro předání článku k publikaci na webu pro autora článku pověřený pracovník připraví v repozitáři https://github.com/opendata-mvcr/opendata-mvcr.github.io feature branch s názvem “feature/název článku” (případně můžete branch založit sami). Úkolem autora je článek uložit do připravené feature branche. Kontrolu, jak článek bude vypadat v reálu, je možné dělat pomocí technologie Jekyll (viz kapitola Technická stránka: Pro zdatné s GitHubem apod.). Po vložení článku je třeba udělat Pull Request z branche s článkem do branche “develop” a nastavit jako reviewera pověřené pracovníky. Zdrojové kódy aplikací je třeba rovněž nahrát na github - pokud aplikace vznikla v rámci KODI, musí být v organizaci opendata -mvcr založen repozitář s aplikací (minimálně klon od autora z doby psaní článku, pokud aplikace nevznikala přímo v opendata-mvcr) s projektovou publicitou. Z článku pak musí vést odkaz na daný repozitář. Pro založení repozitářů kontaktujte pověřeného pracovníka.

  3. Následuje základní technická kontrola, pak dojde k mergnutí Pull Requestu do branche Develop. Vaše branch pro článek zatím zůstává zachována.

  4. Poté pověřený pracovník udělá Pull Request z develop branche do master a článek projde finální korekturou (provede autor, OHA, další pověřený pracovník) s využitím testovacího prostředí https://pod-test.mvcr.gov.cz/články/.
    Během kroku 2., 3. a 4. by měl být autor připraven průběžně zapracovávat požadované úpravy v součinnosti s pověřeným pracovníkem.

  5. Po finalizaci všech kor ektur pověřený pracovník mergne do Masteru a článek bude publikován. V této fázi se také maže feature branch s Vaším článkem. Pozor: v rámci tohoto kroku je třeba nastavit správné datum a čas publikace v hlavičce, čas na 7:00.

  6. Pokud jsou i po publikaci článku nalezeny chyby, nebo vyžadovány úpravy na základě zpětné vazby (např. twitter), pro jejich odstranění je třeba celý proces opakovat,ve zrychleném režimu a bez tweetu a notifikace MVČR. (autor na to má 48 hodin, aby chybu opravil).

POZOR: Součástí odevzdání článku je také vytvoření návrhu tweetu, odkazu na datovou sadu, názvu použité datové sady (toto vše vyplňuje autor společně s odevzdáním).
Technická stránka: Pro zdatné s GitHubem apod. Web data.gov.cz tvoříme na GitHubu pomocí technologie Jekyll. Pokud si tedy zprovozníte Git a Jekyll u sebe, můžete článek ve formě novinky či datového článku dotáhnout až ke commitu/pull requestu do feature/název článku branche. Článek patří do _clanky/<jméno- článku-lowercase-s-mínusem-místo-mezery>.md. Pokud jsou k němu nějaké přílohy, tak ty patří do attachments/články/<jméno-článku-lowercase-s-mínusem-místo- mezery>/<co-chcete>. Technická stránka: Pro… méně zdatné Připravte adresář, ve kterém bude textový soubor s příponou .md obsahující text, a podadresáře “obrázky”, případně “přílohy” apod. obsahující další soubory nalinkované z textu. Následně toto nahrajte do článku přiděleného adresáře na Google Drivu a zadejte v Trellu úkol vybranému členovi z technické části projektu pro vystavení na web. Formát a nástroje pro psaní textů Pro psaní textů budeme používat Kramdown, což je dialekt obecného Markdownu. Výhodou je, že k psaní textu lze použít kterýkoliv textový editor typu Notepad, případně Notepad++ nebo Visual Studio Code pro psaní offline, nebo i online editorů jako je Online Kramdown Editor či Dillinger, které ukazují rovnou i vykreslený text v HTML.

Text budeme psát jednu větu na jeden řádek. Usnadní to pak následné recenze na GitHubu, kde se dá odkázat na řádek, nikoliv na jeho část.

Veškeré textové dokumenty musí být v kódu UTF-8. Nadpisy Dodržujeme hierarchii nadpisů. Tedy článek má nadpis první úrovně s názvem článku, další dělení probíhá pomocí nadpisů druhé úrovně, pak třetí, atd. V žádném případě nevolíme úrovně nadpisů tak, aby “to bylo menší/větší”. Dále dodržujeme pravidlo, že mezi každými 2 nadpisy musí být text. Tedy neměl by být nadpis celého článku a pod ním hned nadpis druhé úrovně. Mezi těmito nadpisy je typicky úvod/abstrakt.

Nadpisy v Kramdownu tvoříme pomocí počtu “#” před textem nadpisu.

Ahoj, jsem nadpis 2. úrovně

Ahoj, jsem nadpis 3. úrovně

Důležité je míti mezeru mezi “#” a začátkem textu nadpisu, aby se syntaxe zobrazila správně.

Anotace Text na začátku článku je anotace neboli úvodní představení toho, o čem článek bude. Ten se pak na webu použije i jako “upoutávka na článek” na home page. To znamená, že v rámci Obecného zadání pro tvorbu článků se jedná o sekci č. 1. Po napsání této sekce v Kramdown souboru použijte syntaxi <!--more-->, který automaticky ze začátku článku vytvoří “upoutávku” na home page Portálu otevřených dat. Anotace je omezena na počet 3 -5 řádků, aby to na hlavní straně vypadalo vždy stejně..

K článku je možné přidat i úvodní obrázek. Odkaz na něj patří do hlavičky (front matter), do klíče image. Odkazy Texty píšeme primárně pro Web, tedy p lně využíváme hypertextové povahy - odkazy vždy vedou z textu, který vhodně sumarizuje, co se za odkazem skrývá, a URL by čtenář v podstatě neměl vidět. Zakázány jsou zejména odkazy typu “více zde”, “další” apod., které toto pravidlo nesplňují. Pro usnadně ní pozdějšího převodu do tištěné podoby ale budeme v Kramdownu používat “reference” syntaxi, kde odkazy jsou definovány na konci textu, tedy například:

A link to the homepage.

Konkrétní příklad:

Odkaz na web Hackathonu veřejné správy přímo v textu uděláme takto:

  1. Syntaxe se skládá ze dvou hranatých závorek
  2. První závorka popisuje text, který má být zobrazen v textu
  3. Druhá závorka popisuje konkrétní odkaz (v našem případě: “ https://hackujstat.cz/”). Jelikož potřebujeme odkazy uvádět až na konci v sekci zdroje pro snadnější manipulaci s textem v budoucnu, do druhé závorky přímo v textu napíšeme “referenci”, kterou poté na konci souboru d efinujeme takto: [reference]: webová stránka “text pro tooltip (text po najetí myší na odkaz)”

Na stránce to bude vypadat v textu takto:

Vítězné projekty jsou uvedeny na [webové stránce Hackathonu veřejné správy] [hackujstat].

A dole v sekci zdroje bude uvedeno toto: [hackujstat]: https://hackujstat.cz/ "Hackathon veřejné správy"

Offline citace Pokud je třeba odkazovat na offline zdroje, nejlepším způsobem bude použít poznámku pod čarou podobnou syntaxí jako u online odkazu:

This is a text with a footnote[^1].

[^1]: And here is the definition.

Konkrétní příklad v Kramdownu:

Poznámku pod čarou jako citaci knihy Právo informační technologií přímo v textu vytvoříme takto:

  1. Syntaxe se skládá z [^X], kde X = číslo poznámky pod čarou.
  2. Dávejte pozor na číslování poznámek pod čarou, které je sice po technické stránce automatické, jak jsme zvyklí, ale z praktického hlediska správného zobrazení posloupnosti čísel poznámek pod čarou je nutné ho mít popořadě v textu.
  3. Citaci poté uvedene na úplny konec textu před definice referencí odkazů popsaných výše. Od textu sekci citací oddělíme pomocí “-------”. Opět tedy uvedeme [^X]: “citace knihy”.

Ve finále to bude vypadat v textu takto:

“Autorská práva jsou osobní a majetková.” [^1].

A dole v sekci vyhrazené pro citace a oddělené pomocí “-------” to bude uvedeno takto: [^1]: Radim Polčák a kolektiv vydal: Wolters Kluwer, a. s., podle stavu k 11. 10. 2018, 656 stran ISBN: 978-80-7598-045-8 Tabulky Často mají autoři nutkání strukturovat text pomocí tabulek. Zde platí jednoduché pravidlo: pokud to, co chceme strukturovat, má povahu statistické tabulky, tedy taková tabulka je plná čísel a je nutné, aby byla zobrazována jako tabulka, použití tabulky je v pořádku. V ostatních případech se tabulka nepoužívá, a místo ní se použije typicky definiční seznam, nebo běžně strukturovaný text (tedy odstavce a nadpisy odpovídajících úrovní). Pro přípravu markdown tabulek třeba z CSV lze použít například Markdown Tables generator.

Definiční seznam v Kramdownu se vytvoří takto:

  1. “Slovo které chceme definovat” a které bude ve finále na obrazovce tučně
  2. Na další řádku je definice tohoto slova, která začíná “:” mezera “definice”

Zápis tak bude vypadat takto:

Otevřená data : Otevřenými daty se pro účely tohoto zákona rozumí informace zveřejňované způsobem umožňujícím dálkový přístup v otevřeném a strojově čitelném formátu, jejichž způsob ani účel následného využití není omezen a které jsou evidovány v národním katalogu otevřených dat.

A ve finále se to pro čtenáře zobrazí takto:

Otevřená data Otevřenými daty se pro účely tohoto zákona rozumí informace zveřejňované způsobem umožňujícím dálkový přístup v otevřeném a strojově čitelném formátu, jejichž způsob ani účel následného využití není omezen a které jsou evidovány v národním katalogu otevřených dat.

Obrázky Obrázky připravujeme ve vektorovém formátu SVG, pokud to lze. Pokud ne, pak v bitmapovém formátu WebP v případě screenshotů a fotografií. Pokud používáte obrázky od 3. osob, nezapomeňte uvést citaci obrázku do popisku. Obrázky se umisťují do adresáře /attachments/články/<název článku>/obrázky/. Pokud má být obrázek použit v upoutávce na článek v jejich seznamu, je třeba dbát na to, aby nebyl příliš velký, a nebo pro tento účel vytvořit menší kopii.

Kramdown nemá nativní podporu pro obrázky s popisky, a my chceme mít u každého obrázku popisek, případně i s odkazem na zdroj. Proto pro obrázky nepoužijeme nativní Kramdown syntaxi: ![název obrázku](relativní adresa obrázku). Místo toho použijeme následující syntaxi, která v description používá HTML:

{% include image.html
url="../attachments/články/.../obrázky/obrázek1.jpg" description="Foto: <a href='https://hackujstat.cz/' title='Hackuj stát'>Hackathon veřejné správy</a>"
%}

kde url je relativní url k článku a description je jeho popisek v HTML (pro uvedení odkazu na zdroj případně na přidání formou poznámky pod čarou k danému popisku).

Page 1 of 2