Glossary
Terms and abbreviations relevant to this project
Your research project should include a short glossary of the main terms and abbreviations used in the metadata and protocols. This should help the reader to navigate through the index.
In the example below we describe some software tools used in this repository.
Version control and repositories
Git
Git is a system to track changes in files, it is most often used to coordinate the work among several persons who access the files online on a server or sync them to their computer. The online use does not require any installation, local use is only possible after installing Git.
Git repository
A Git repository is a set of folders and files with complete history and full version-tracking abilities, locally or on a server.
Github
Github.com is a commercial hosting service for version control with Git.
Gitlab
Gitlab.com is acommercial hosting services for version control with Git.
Gitlab pages
Gitlab pages is a service from Gitlab that allows you to publish static websites directly from a repository in Gitlab.
Static websites
On a static website the user will just see whatever data is contained in the HTML that composes the website. Anyone landing on that website will see the same content, no new content is generated based on the user’s input.
Continuous Integration and deployment - CI/CD
CI/CD is a method of software development where building, testing and deploying applications is done continuously. A very simple use case example in the context of Gitlab pages is a CI/CD script that is triggered whenever there are changes in the repository, and that renders the website HTML. Thus, enabling maintainers to change and update the website content directly from the browser.
Software and reporting
Dynamic reporting / dynamic content generation
A powerful approach to improve reproducibility of results. Dynamically generated report follow the principles of ’literate programming and contain code, text and code outputs in a single document. The outputs can be figures, tables and can even have interactive elements (for HTML reports). They can be parameterized and they are updated automatically with additions, modifications or deletions from the source code. Learn more in our CRS primer Dynamic Reporting
R
The R language and programming environment was designed for statistical computing and graphics. It is free and open source, broadly used in research and it has a very active community of users.
Rstudio
The integrated development environment (IDE) R studio is free and open source. It is the recommended software to use for R and Quarto as the latest versions support editing and previewing Quarto documents. The desktop application R studio includes a console, syntax-highlighting editor as well as tools for plotting, history, debugging and workspace management.
Quarto
The multi-language publishing system Quarto is an open-source scientific and technical publishing system. It is more advanced than R markdown with more options for output types and languages. It can generate dynamic reports in different formats (e.g., pdf, HTML, MS word, ePub) with content written in different languages (R, Python, Julia and Observable). When used in R, we have the Quarto Markdown files (.qmd) containing a YAML header, text written in Markdown and code chunks written in R.
Human-readable syntaxes
These are simple languages used for formatting and/or for specifying settings in many of the software tools and workflows we describe. They require a very minimal learning from users, and there are plenty of templates and examples online. A good approach is usually to build on some of them and adapt it to our case.
Markdown
Markdown, a lightweight markup language with simple syntax that will add formatting elements to plain text. This format is widely used for technical documentation online. Documents in this format can be rendered into formatted text in multiple formats (e.g., pdf, HTML). These documents can contain tables and images (or animations if intended for HTML). There are multiple visual markdown editors to facilitate editing of these documents. The constrained formatting options can benefit researchers by facilitating more consistent and clear documentation styles and its interoperability makes it possible to share in a website or to try out different output formats.
YAML
Originally meaning Yet Another Markup Language, now YAML Ain’t Markup Language YAML is a human-friendly data serialization language for all programming languages which is often used for configuration files. For example, in Quarto we have the _quarto.yml file with the project settings (e.g., specifying if it renders into a website, what should be in the navigation bar, etc). The header of the Quarto markdown files are also written in YAML syntax, same as the project file. In Gitlab continuous integration the CI/CD file (.gitlab-ci.yml) with instructions and settings is also a YAML file.