Documentation for Finnish users / Dokumentaatio suomalaisille käyttäjille

[pitkant]

Interest in Finnish health and welfare indicators may possibly be mainly inside the Finnish context and therefore it may be justified to provide documentation (vignettes / articles etc) for them in Finland's national languages, Finnish and Swedish. The rest of this issue description is going to be in Finnish.

---

sotkanet-paketin käyttäjät saattavat todennäköisesti olla pääasiassa suomalaisia, jolloin paketin dokumentaatio olisi käyttäjäystävällisyyden nimissä hyvä olla myös suomeksi, ruotsiksi ja mahdollisesti myös muilla Suomessa käytetyillä kielillä.

Voit auttaa konkreettisesti paketin kehitystyössä esimerkiksi:

• kirjoittamalla blogikirjoituksen jossa pakettia hyödynnetään omassa kontekstissa
• kirjoittamalla vigneten (pitkä dokumentaatiomuoto) joka liitetään osaksi paketin lähdekoodia CRAN-jakelussa (https://cran.r-project.org/package=hetu)
• kirjoittamalla artikkelin joka liitetään osaksi paketin nettisivuja (ropengov.github.io/hetu)

Hyvän vignetten kirjoitusohjeet löytyvät mm. Wickhamin ja Bryanin R Packages -verkkokirjan kappaleesta Vignettes: long-form documentation:

"A vignette is like a book chapter or an academic paper: it can describe the problem that your package is designed to solve, and then show the reader how to solve it. A vignette should divide functions into useful categories, and demonstrate how to coordinate multiple functions to solve problems. Vignettes are also useful if you want to explain the details of your package. For example, if you have implemented a complex statistical algorithm, you might want to describe all the details in a vignette so that users of your package can understand what’s going on under the hood, and be confident that you’ve implemented the algorithm correctly."

Dokumentaation kirjoittaminen lasketaan osaksi paketin kehitystyötä ja kirjoittajat saavat ansaitsemansa tunnustuksen tekemästään työstä. Dokumentaation kääntäminen on hyvä keino tutustua Git-versionhallintajärjestelmän käyttöön. Vastaamme mielellämme kontribuution toteuttamiseen liittyviin kysymyksiin esimerkiksi tässä issue-keskustelussa.

Git-versionhallintajärjestelmän käyttöön on avoimesti suoritettava 3 opintopisteen kurssi FITechin kurssivalikoimassa: GIT Open

[pitkant]

New, rewritten vignette should refer to new function names exclusively. Old vignette could be retained (maybe as an article in the web page) so people who have legacy code could still look up instructions on how to do things but we should encourage people to use the new functions from now on, even if we don't remove them