Highlight INBO package vignettes as tutorials
Closed this issue · 8 comments
A lot of tutorial-like material is written as vignettes/articles in (INBO) R packages. We should find a way to highlight these on the tutorials website. Either as:
- One-to-one tutorial vignette, where the index.md file contains the vignette title and a link. Advantage: vignettes are tutorials and can be organized the same way
- A single page listing all vignettes (cf. how we list all the package on one page). Advantage: not too much work.
One-to-one tutorial vignette, where the index.md file contains the vignette title and a link. Advantage: vignettes are tutorials and can be organized the same way
In all cases, the relationship between package X and tutorial A, B and C should remain clear on the website. I think this is easiest accomplished for the second option (a page that enlists (linked) vignettes grouped per software package, or perhaps one such page for each package).
With the first option above, these relationships may not be apparent in an index of the tutorials, unless the titles are prefixed with a package name on the tutorials website. Package vignette titles are often not 'self-contained', but to be understood within the context of a package (e.g.: 'Getting started').
Best also consider here the need to auto-update the information provided in https://inbo.github.io/tutorials/articles/inbo_software/.
I like the one-to-one because it brings all vignettes to the same level as tutorials. I would indeed prefix the title with the package name. E.g.:
---
title: "`camtrapdp`: Visualize deployment features"
description: "This vignette shows how to use function `map_dep()` to visualize two important deployment features on a leaflet map."
authors: [damianooldoni]
date: 2021-06-06
categories: ["r"]
tags: ["r", "camera trap"]
output:
md_document:
preserve_yaml: true
variant: markdown_github
---
See <https://inbo.github.io/camtrapdp/articles/visualize-deployment-features.html>.I'm also in favour of the first option, it seems more straightforward for visitors of the tutorials site to search for a certain subject and find either a tutorial or a link to a package vignette. I'm not sure visitors will do the effort to additionally search on a list with diverse subjects if something fits their needs. (Similarly I get the impression that the web page with INBO packages is not known by the majority of the INBO R users and probably hardly visited...)
For inbodb we already had in mind to replace the tutorial here by a link to the package vignette (issue #37).
Regarding the overview (table) of all INBO software, my opinion on that is that we should find a way to make it more visible / findable. Rather than drop it: I don't believe the oversight (and interrelations) which this table offers would be satisfactorily replaced by enlisting package vignettes among the other tutorials on the website (which, in itself, I find a good thing to do - thanks for clarifying @peterdesmet).
Perhaps the tutorials website is not the most appropriate place for the overview and the INBO website itself might be better suited. But then, I don't know how this could be integrated with an automated workflow.
@florisvdh Of course we shouldn't drop the overview of the INBO packages. To make it more visible: maybe we could add the link in the introduction of the main page, where we refer to the development of software? (And maybe it also deserves a place somewhere in the fixed template of the the open science nieuwsbrief?)
It is certainly a good overview of which packages are available at inbo, but the problem is that the majority of the users of the tutorials website are probably looking for some very specific information on what they are doing: how do I read a GIS map in R? How do I query a database? ... As I haven't found another easy possibility to navigate in the website other than clicking on the tags, I suppose most other visitors also use this method to quickly navigate to a subject that meets their information need. So in my opinion, relevant packages (such as inbodb for database queries) should pop up here, together with the tutorials. I'm not sure we need an automated workflow to add all inbo made packages (some are very specific data providing packages, and maybe they would rather fit in an overview divided per subject, e.g. forests / vegetation / species / water /...), but it would be good to have a template easily available for the packages where it makes sense to add the vignette as a tutorial. (Apparently INBOmd and inborutils even have their own tag, which is maybe not necessary for each inbo package, but I will anyway replace this tutorial under the database tag with a link to the vignette, as we don't want to keep this information up-to-date in 2 places.) If the example of @peterdesmet would be available as a rmarkdown template, it would take about 5 minutes to provide the necessary information and submit the vignette as a tutorial, which seems not too much work for a package maintainer to (hopefully) increase the user group of his/her package by incorporating the vignette as a tutorial. I would certainly do this effort for relevant packages as inbodb, but I find less useful (rather an overload for the website) to also add packages that focus on a subject that is only studied in 1 team (while I would certainly add these packages to the inbo packages overview).
To make it more visible: maybe we could add the link in the introduction of the main page, where we refer to the development of software?
I think that's a great idea @ElsLommelen. Also just discussed with @LienReyserhove. I'll suggest to include it in #145.