{"id":691,"date":"2024-03-22T14:17:52","date_gmt":"2024-03-22T12:17:52","guid":{"rendered":"https:\/\/www.index.fi\/?page_id=691"},"modified":"2025-09-05T11:16:52","modified_gmt":"2025-09-05T08:16:52","slug":"dita-docsascode","status":"publish","type":"page","link":"https:\/\/www.index.fi\/fi\/tietopankki\/dita-docsascode\/","title":{"rendered":"DITA Docs as Code"},"content":{"rendered":"
<\/i>

Docs as Code<\/h1><\/div>

Mit\u00e4 on Docs as Code?<\/b><\/p>\n

Dokumentaation tyypillinen ongelma on se, ett\u00e4 se j\u00e4\u00e4 j\u00e4lkeen tuoteversioista tai se ei vastaa modulaarisen tuotteen eri versioita. Modulaarisella l\u00e4hestymistavalla voidaan kohdentaa dokumentaatio vastaamaan tuotekonfiguraatiota. Menetelm\u00e4n tavoitteena on yhdist\u00e4\u00e4 tuotteen ja sen dokumentaation kehitys. T\u00e4m\u00e4 saavutetaan soveltamalla dokumentointiin samoja hyv\u00e4ksi havittuja ty\u00f6kaluja ja menetelmi\u00e4 kuin ohjelmistokehitykseen. N\u00e4m\u00e4 ty\u00f6kalut ja menetelm\u00e4t vaihtelevat organisaatioittain. Docs as Coden l\u00e4ht\u00f6kohdat ovat:<\/p>\n

– Dokumentti on standarditekstiformaatissa, kuten DITA, HTML tai Markdown. N\u00e4it\u00e4 voidaan muokata niille kehitetyill\u00e4 tekstieditoreilla, esimerkiksi Oxygen XML Editor.<\/p>\n

– Palvelunhallintaj\u00e4rjestelm\u00e4 (esim. Jira) muutostenhallintaan, jota k\u00e4ytet\u00e4\u00e4n tyypillisesti my\u00f6s ohjelmistokehityksess\u00e4. Tarkoituksena on varmistaa, ett\u00e4 tuotteen muutokset n\u00e4kyv\u00e4t my\u00f6s dokumentaatiossa.<\/p>\n

– Versiohallinta (Git), Docs as Code -menetelm\u00e4ss\u00e4 dokumentointi tyypillisesti seuraa dokumentoitavan tuotteen versioita. Vaihtoehtoisesti voidaan k\u00e4ytt\u00e4\u00e4 Indox CCMS -j\u00e4rjestelm\u00e4\u00e4, jossa on tuki ty\u00f6nkuluille.<\/p>\n

– Automaattinen dokumentaation koostaminen ja jakelu. Mik\u00e4li dokumentaatioon tulee muutoksia se laukaisee koostamisen, jonka my\u00f6t\u00e4 syntyy uudelle versiolle sopiva dokumentaatio. T\u00e4m\u00e4 vastaa ohjelmistokehityksen CI\/CD-ajattelua, eli jatkuvaa integraatiota ja jatkuvaa toimitusta. Dokumentaation modulaarisuuden ansiosta voidaan koostamisessa kohdentaa dokumentaatio vastaamaan asiakkaan tuotekonfiguraatiota.<\/p>\n

– Dokumentaation testaus voidaan automatisoida esim. validoimalla DTD\/skeemaa vastaan ja k\u00e4ytt\u00e4m\u00e4ll\u00e4 terminologian tarkastukseen automaatiota kuten Vale-sovellusta.<\/p>\n

– Dokumentointi yhdistet\u00e4\u00e4n k\u00e4ytett\u00e4v\u00e4\u00e4n kehitysmenetelm\u00e4\u00e4n. Esimerkiksi ohjelmistokehityksen Scrum, jolloin dokumentointi tehd\u00e4\u00e4n osana sprinttej\u00e4.<\/p>\n

Docs as Code -menetelm\u00e4 voidaan toteuttaa siten, ett\u00e4 koko kehitystiimi on vastuussa dokumentaatiosta. Ohjelmistokehitt\u00e4j\u00e4t osallistuvat dokumentointiin osana kehitysty\u00f6t\u00e4 kirjoittamalla Markdownilla tai DITAlla. Tekniset kirjoittajat stilisoivat ja j\u00e4rjestelev\u00e4t aineiston.<\/p>\n

DITA sopii erinomaisesti Docs as Code -menetelm\u00e4\u00e4n<\/b><\/p>\n

DITA on Oasis-standardin mukainen tekstipohjainen formaatti, joka on mahdollistaa aineiston siirron j\u00e4rjestelm\u00e4st\u00e4 toiseen tai ty\u00f6kalujen vaihtamisen vaivatta. DITAan voi yhdist\u00e4\u00e4 muitakin tekstipohjaisia formaatteja, kuten Markdown ja HTML (LWDITA). Tekstipohjaisuuden ansiosta voidaan k\u00e4ytt\u00e4\u00e4 versiointity\u00f6kaluja ja vertailu on helppoa. DITAn modulaarisuus ja uudelleenk\u00e4ytett\u00e4vyys helpottavat erilaisten dokumenttikokonaisuuksien koostamista samasta l\u00e4hdeaineistosta. DITA mahdollistaa useat erilaiset jakeluformaatit, kuten html (WebHelp) ja PDF. Julkaisu tehd\u00e4\u00e4n tyypillisesti k\u00e4ytt\u00e4en vapaanl\u00e4hdekoodin DITA-OT-ty\u00f6kalua. DITAn semanttisuus mahdollistaa monimuotoisen testaamisen. Konteksti voidaan huomioida testaamisessa, esimerkiksi otsikot pit\u00e4\u00e4 olla tietyss\u00e4 muodossa.<\/p>\n

Johtop\u00e4\u00e4t\u00f6kse<\/b>t<\/p>\n

DITA sopii hyvin Docs as Code -menetelm\u00e4\u00e4n. DITAlla voidaan tehd\u00e4 monimutkaista dokumentaatiota, mutta helpompaan dokumentaatioon se voidaan pit\u00e4\u00e4 yksinkertaisena. DITA mahdollistaa dokumentaation hallitun kehittymisen tuotteen monimutkaistuessa vuosien aikana. Index IT auttaa organisaatiotasi siirtym\u00e4\u00e4n Docs as Code -menetelm\u00e4\u00e4n.<\/p>\n

L\u00e4hteet:<\/p>\n

https:\/\/istc.org.uk\/wp-content\/uploads\/2021\/11\/George-Bina-%E2%80%93-Docs-as-Code-and-DITA.pdf<\/a><\/p>\n<\/div><\/div><\/div><\/div><\/div>\n","protected":false},"excerpt":{"rendered":"","protected":false},"author":1,"featured_media":0,"parent":686,"menu_order":0,"comment_status":"closed","ping_status":"closed","template":"100-width.php","meta":{"footnotes":""},"class_list":["post-691","page","type-page","status-publish","hentry"],"yoast_head":"\nDITA Docs as Code - Index IT<\/title>\n<meta name=\"description\" content=\"Mit\u00e4 on Docs as Code? Tutustu menetelm\u00e4\u00e4n, jossa dokumentointi integroidaan ohjelmistokehitykseen versionhallinnan, automaation ja CI\/CD-mallien avulla.\" \/>\n<meta name=\"robots\" content=\"index, follow, max-snippet:-1, max-image-preview:large, max-video-preview:-1\" \/>\n<link rel=\"canonical\" href=\"https:\/\/www.index.fi\/fi\/tietopankki\/dita-docsascode\/\" \/>\n<meta property=\"og:locale\" content=\"fi_FI\" \/>\n<meta property=\"og:type\" content=\"article\" \/>\n<meta property=\"og:title\" content=\"DITA Docs as Code - Index IT\" \/>\n<meta property=\"og:description\" content=\"Mit\u00e4 on Docs as Code? Tutustu menetelm\u00e4\u00e4n, jossa dokumentointi integroidaan ohjelmistokehitykseen versionhallinnan, automaation ja CI\/CD-mallien avulla.\" \/>\n<meta property=\"og:url\" content=\"https:\/\/www.index.fi\/fi\/tietopankki\/dita-docsascode\/\" \/>\n<meta property=\"og:site_name\" content=\"Index IT\" \/>\n<meta property=\"article:modified_time\" content=\"2025-09-05T08:16:52+00:00\" \/>\n<meta name=\"twitter:card\" content=\"summary_large_image\" \/>\n<meta name=\"twitter:label1\" content=\"Arvioitu lukuaika\" \/>\n\t<meta name=\"twitter:data1\" content=\"3 minuuttia\" \/>\n<script type=\"application\/ld+json\" class=\"yoast-schema-graph\">{\"@context\":\"https:\\\/\\\/schema.org\",\"@graph\":[{\"@type\":\"WebPage\",\"@id\":\"https:\\\/\\\/www.index.fi\\\/fi\\\/tietopankki\\\/dita-docsascode\\\/\",\"url\":\"https:\\\/\\\/www.index.fi\\\/fi\\\/tietopankki\\\/dita-docsascode\\\/\",\"name\":\"DITA Docs as Code - Index IT\",\"isPartOf\":{\"@id\":\"https:\\\/\\\/www.index.fi\\\/#website\"},\"datePublished\":\"2024-03-22T12:17:52+00:00\",\"dateModified\":\"2025-09-05T08:16:52+00:00\",\"description\":\"Mit\u00e4 on Docs as Code? Tutustu menetelm\u00e4\u00e4n, jossa dokumentointi integroidaan ohjelmistokehitykseen versionhallinnan, automaation ja CI\\\/CD-mallien avulla.\",\"breadcrumb\":{\"@id\":\"https:\\\/\\\/www.index.fi\\\/fi\\\/tietopankki\\\/dita-docsascode\\\/#breadcrumb\"},\"inLanguage\":\"fi\",\"potentialAction\":[{\"@type\":\"ReadAction\",\"target\":[\"https:\\\/\\\/www.index.fi\\\/fi\\\/tietopankki\\\/dita-docsascode\\\/\"]}]},{\"@type\":\"BreadcrumbList\",\"@id\":\"https:\\\/\\\/www.index.fi\\\/fi\\\/tietopankki\\\/dita-docsascode\\\/#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"Etusivu\",\"item\":\"https:\\\/\\\/www.index.fi\\\/fi\\\/\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"Tietopankki\",\"item\":\"https:\\\/\\\/www.index.fi\\\/fi\\\/tietopankki\\\/\"},{\"@type\":\"ListItem\",\"position\":3,\"name\":\"DITA Docs as Code\"}]},{\"@type\":\"WebSite\",\"@id\":\"https:\\\/\\\/www.index.fi\\\/#website\",\"url\":\"https:\\\/\\\/www.index.fi\\\/\",\"name\":\"Index IT\",\"description\":\"Index IT\",\"publisher\":{\"@id\":\"https:\\\/\\\/www.index.fi\\\/#organization\"},\"potentialAction\":[{\"@type\":\"SearchAction\",\"target\":{\"@type\":\"EntryPoint\",\"urlTemplate\":\"https:\\\/\\\/www.index.fi\\\/?s={search_term_string}\"},\"query-input\":{\"@type\":\"PropertyValueSpecification\",\"valueRequired\":true,\"valueName\":\"search_term_string\"}}],\"inLanguage\":\"fi\"},{\"@type\":\"Organization\",\"@id\":\"https:\\\/\\\/www.index.fi\\\/#organization\",\"name\":\"Index IT\",\"url\":\"https:\\\/\\\/www.index.fi\\\/\",\"logo\":{\"@type\":\"ImageObject\",\"inLanguage\":\"fi\",\"@id\":\"https:\\\/\\\/www.index.fi\\\/#\\\/schema\\\/logo\\\/image\\\/\",\"url\":\"https:\\\/\\\/www.index.fi\\\/wp-content\\\/uploads\\\/2023\\\/09\\\/Logo_digi.png\",\"contentUrl\":\"https:\\\/\\\/www.index.fi\\\/wp-content\\\/uploads\\\/2023\\\/09\\\/Logo_digi.png\",\"width\":2165,\"height\":570,\"caption\":\"Index IT\"},\"image\":{\"@id\":\"https:\\\/\\\/www.index.fi\\\/#\\\/schema\\\/logo\\\/image\\\/\"},\"sameAs\":[\"https:\\\/\\\/www.linkedin.com\\\/company\\\/index-information-technologies-oy\\\/\"]}]}<\/script>\n<!-- \/ Yoast SEO plugin. -->","yoast_head_json":{"title":"DITA Docs as Code - Index IT","description":"Mit\u00e4 on Docs as Code? Tutustu menetelm\u00e4\u00e4n, jossa dokumentointi integroidaan ohjelmistokehitykseen versionhallinnan, automaation ja CI\/CD-mallien avulla.","robots":{"index":"index","follow":"follow","max-snippet":"max-snippet:-1","max-image-preview":"max-image-preview:large","max-video-preview":"max-video-preview:-1"},"canonical":"https:\/\/www.index.fi\/fi\/tietopankki\/dita-docsascode\/","og_locale":"fi_FI","og_type":"article","og_title":"DITA Docs as Code - Index IT","og_description":"Mit\u00e4 on Docs as Code? Tutustu menetelm\u00e4\u00e4n, jossa dokumentointi integroidaan ohjelmistokehitykseen versionhallinnan, automaation ja CI\/CD-mallien avulla.","og_url":"https:\/\/www.index.fi\/fi\/tietopankki\/dita-docsascode\/","og_site_name":"Index IT","article_modified_time":"2025-09-05T08:16:52+00:00","twitter_card":"summary_large_image","twitter_misc":{"Arvioitu lukuaika":"3 minuuttia"},"schema":{"@context":"https:\/\/schema.org","@graph":[{"@type":"WebPage","@id":"https:\/\/www.index.fi\/fi\/tietopankki\/dita-docsascode\/","url":"https:\/\/www.index.fi\/fi\/tietopankki\/dita-docsascode\/","name":"DITA Docs as Code - Index IT","isPartOf":{"@id":"https:\/\/www.index.fi\/#website"},"datePublished":"2024-03-22T12:17:52+00:00","dateModified":"2025-09-05T08:16:52+00:00","description":"Mit\u00e4 on Docs as Code? Tutustu menetelm\u00e4\u00e4n, jossa dokumentointi integroidaan ohjelmistokehitykseen versionhallinnan, automaation ja CI\/CD-mallien avulla.","breadcrumb":{"@id":"https:\/\/www.index.fi\/fi\/tietopankki\/dita-docsascode\/#breadcrumb"},"inLanguage":"fi","potentialAction":[{"@type":"ReadAction","target":["https:\/\/www.index.fi\/fi\/tietopankki\/dita-docsascode\/"]}]},{"@type":"BreadcrumbList","@id":"https:\/\/www.index.fi\/fi\/tietopankki\/dita-docsascode\/#breadcrumb","itemListElement":[{"@type":"ListItem","position":1,"name":"Etusivu","item":"https:\/\/www.index.fi\/fi\/"},{"@type":"ListItem","position":2,"name":"Tietopankki","item":"https:\/\/www.index.fi\/fi\/tietopankki\/"},{"@type":"ListItem","position":3,"name":"DITA Docs as Code"}]},{"@type":"WebSite","@id":"https:\/\/www.index.fi\/#website","url":"https:\/\/www.index.fi\/","name":"Index IT","description":"Index IT","publisher":{"@id":"https:\/\/www.index.fi\/#organization"},"potentialAction":[{"@type":"SearchAction","target":{"@type":"EntryPoint","urlTemplate":"https:\/\/www.index.fi\/?s={search_term_string}"},"query-input":{"@type":"PropertyValueSpecification","valueRequired":true,"valueName":"search_term_string"}}],"inLanguage":"fi"},{"@type":"Organization","@id":"https:\/\/www.index.fi\/#organization","name":"Index IT","url":"https:\/\/www.index.fi\/","logo":{"@type":"ImageObject","inLanguage":"fi","@id":"https:\/\/www.index.fi\/#\/schema\/logo\/image\/","url":"https:\/\/www.index.fi\/wp-content\/uploads\/2023\/09\/Logo_digi.png","contentUrl":"https:\/\/www.index.fi\/wp-content\/uploads\/2023\/09\/Logo_digi.png","width":2165,"height":570,"caption":"Index IT"},"image":{"@id":"https:\/\/www.index.fi\/#\/schema\/logo\/image\/"},"sameAs":["https:\/\/www.linkedin.com\/company\/index-information-technologies-oy\/"]}]}},"_links":{"self":[{"href":"https:\/\/www.index.fi\/fi\/wp-json\/wp\/v2\/pages\/691","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/www.index.fi\/fi\/wp-json\/wp\/v2\/pages"}],"about":[{"href":"https:\/\/www.index.fi\/fi\/wp-json\/wp\/v2\/types\/page"}],"author":[{"embeddable":true,"href":"https:\/\/www.index.fi\/fi\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/www.index.fi\/fi\/wp-json\/wp\/v2\/comments?post=691"}],"version-history":[{"count":7,"href":"https:\/\/www.index.fi\/fi\/wp-json\/wp\/v2\/pages\/691\/revisions"}],"predecessor-version":[{"id":1240,"href":"https:\/\/www.index.fi\/fi\/wp-json\/wp\/v2\/pages\/691\/revisions\/1240"}],"up":[{"embeddable":true,"href":"https:\/\/www.index.fi\/fi\/wp-json\/wp\/v2\/pages\/686"}],"wp:attachment":[{"href":"https:\/\/www.index.fi\/fi\/wp-json\/wp\/v2\/media?parent=691"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}