add complementary writing guidelines

**Question:** Where and how to add all this information in the CONTRIBUTING file?

Ideas in #80

---------

In:

https://github.com/epiverse-trace/tutorials/blob/ad7dd941a34071bde49b8140f9ab84068314bbd1/CONTRIBUTING.md?plain=1#L132

# For Workbench novice users:

- Follow the steps to [create a new lesson locally](https://carpentries.github.io/sandpaper-docs/introduction.html#create-a-lesson-locally).
- Build the new lesson with `sandpaper::build_lesson()`.
- If you have any issues with this, report back for support.

# Add in the [Developers](https://github.com/epiverse-trace/tutorials/blob/main/CONTRIBUTING.md#developer):

- Render lesson with [`sandpaper::build_lesson()`](https://carpentries.github.io/sandpaper/reference/build_lesson.html). This will open an HTML tab in your browser to review. This HTML format is how the website is going to look online (without the epiverse-trace `{varnish}` [epiverse theme](https://github.com/epiverse-trace/varnish/tree/epiversetheme) or [tracelac theme](https://github.com/epiverse-trace/varnish/tree/tracelactheme)).
- Create a new episode:
- run `sandpaper::create_episode_rmd(title, add)` or
- make a copy of the file or callouts in [`episodes/template.Rmd`](https://github.com/epiverse-trace/tutorials/blob/main/episodes/template.Rmd)
- Read about [How to edit the workbench](https://carpentries.github.io/sandpaper-docs/editing.html).
- Do not include code lines to install packages like `install.packages()` or `pak::pak()` inside an episode file. We rely on [`{renv}` via `{sandpaper}`](https://github.com/epiverse-trace/tutorials/issues/16) to keep a stable package version to render the website and automatic workflows to notify of any unexpected changes.
- Read about how to [add new entries to the glossary](https://github.com/epiverse-trace/tutorials/issues/32) to expand on definitions.
- Cite papers as links `[author et al., year](link)` since this format does not supports bib files.
- Read about how to [add footnotes](https://github.com/carpentries/workbench/discussions/63 ) using a syntax like `[^1]`
- Read about the [core workbench style guides](https://carpentries.github.io/sandpaper-docs/style.html) for figures, divs, and line length.
- Read [issues labelled with `to-keep`](https://github.com/epiverse-trace/tutorials/issues?q=is%3Aissue+label%3A%22to+keep%22+) read new features we want to keep in this repo.
- When creating your PR, resolve conflicts locally using [`git rebase`](https://github.com/epiverse-trace/tutorials/blob/main/CONTRIBUTING.md#rebase). This:
- Allows running GH-actions to evaluate if the contribution passes all the validation checks.
- Facilitates PR review ([ref](https://github.com/epiverse-trace/tutorials/pull/110#issuecomment-1908837561))
- Use `{lintr}` addin to "Lint current file" from [Rstudio or other editors](https://lintr.r-lib.org/articles/editors.html).
- This prefer portable paths with `file.path()` for developer and `here()` for learner view.
- This prefer `withr::local_options()` instead of `options()`
- `{lintr}` is run in all PRs as a GitHub Actions workflow to adhere to the [tidyverse style guide](https://style.tidyverse.org/).
- For self-created figures we prefer a [`.png` format](https://github.com/epiverse-trace/tutorials/pull/104#pullrequestreview-1864442026), which is more appropriate to be [displayed in modern web browsers](https://www.biomedcentral.com/getpublished/writing-resources/file-formats#png+-+portable+networks+graphics). Any original figure in any other format, should be kept in that original format.
- try to make review branches episode specific. This may imply a request for reviewers to remove non-to-review episodes in `config.yaml` file.
- When contributing, commit only the commits specific to one or two files. Avoid doing `git commit .`. After local rendering, there files that will be suggested to commit, but the developer should avoid.
- Use [full package review](https://epiverse-trace.github.io/blueprints/code-review.html#partial-review) guidelines to collect feedback in whole episodes before and after a material trial.
- To print DiagrammeR and visNetwork outputs use webshot package. Examples and details in https://github.com/epiverse-trace/tutorials/issues/98 [now evaluating to consider mermaid https://github.com/epiverse-trace/tutorials-late/issues/46]
- Add tables using a markdown table generator: https://www.tablesgenerator.com/markdown_tables
- Given agreement in using explicit namespace to all functions https://github.com/epiverse-trace/episoap/issues/91 we need to unlock this check in lintr https://github.com/epiverse-trace/tutorials/issues/119. Locally, you may have this as an issue; it will pass into online workflow actions.
- name packages as `{packagename}` to activate the [code linking](https://quarto.org/docs/output-formats/html-code.html#code-linking) feature in the rendered website.
- We homogenise the use of the magrittr pipe `%>%` (https://github.com/epiverse-trace/tutorials-early/issues/96) and lint for its consistency across the repo (https://github.com/epiverse-trace/tutorials/pull/222)

# Add in the [Maintainers](https://github.com/epiverse-trace/tutorials/blob/main/CONTRIBUTING.md#maintainer):

- Read about the [automated update](https://github.com/epiverse-trace/research-compendium/pull/28#issuecomment-1862652089) of workflows and package cache.
- Create a [WIP Issue](https://github.com/epiverse-trace/tutorials/issues/88) defining the branch name, the task in the roadmap, packages, and the contributor assigned to it.
- Read about how to [create CITATION file](https://github.com/epiverse-trace/research-compendium/pull/19 ) for this type of repository.
- Update the "minimum supported version" annually to the [setup file](https://github.com/epiverse-trace/tutorials/blob/main/learners/setup.md). This follows the [R version support tidyverse policy](https://www.tidyverse.org/blog/2019/04/r-version-support/).
- If need to manually update packages, run action 03: https://github.com/epiverse-trace/tutorials-middle/actions/workflows/update-cache.yaml
- When doing version releases, do it locally to: update the `CITATION.cff` and knit the `README.md`. To add to Zenodo, follow the steps in [Zenodo > Settings > GitHub](https://zenodo.org/account/settings/github/) then submit to Epiverse-TRACE community following steps in [Zenodo > Submit to community](https://help.zenodo.org/docs/share/submit-to-community/#submit). Paste Zenodo DOI on README.

## Repositories to maintain

There are monthly updates on repositories:

- [x] https://github.com/epiverse-trace/tutorials/pulls
- [x] https://github.com/epiverse-trace/tutorials-early/pulls
- [ ] https://github.com/epiverse-trace/tutorials-early-fr/pulls
- [x] https://github.com/epiverse-trace/tutorials-middle/pulls
- [ ] https://github.com/epiverse-trace/tutorials-middle-es/pulls
- [ ] https://github.com/epiverse-trace/tutorials-middle-fr/pulls
- [x] https://github.com/epiverse-trace/tutorials-late/pulls
- [ ] https://github.com/epiverse-trace/tutorials-late-fr/pulls (upcoming)
- [ ] https://github.com/epiverse-trace/git-rstudio-basics/pulls
- [ ] https://github.com/epiverse-trace/research-compendium/pulls
- [ ] https://github.com/epiverse-trace/epimodelac/pulls
- [ ] https://github.com/epiverse-trace/epitkit/pulls
- [ ] https://github.com/epiverse-trace/EpiTKit-EN/pulls
- [ ] https://github.com/epiverse-trace/EpiTKit-FR/pulls

Consider that edits can also apply to:

- [ ] https://github.com/epiverse-trace/howto/
- [ ] https://github.com/epiverse-trace/tutorials/tree/main/instructors

## How to review monthly updates in local computer?

- Pull from `main`
- Delete the local copy of the `update/packages` branch: `git branch -D update/packages`
- Switch to `update/packages` branch
- Review the `git log`. The last commit should match the one created by the `[actions]` triggered by `epiverse-trace-bot`
- Restore the package versions automatically updated in the lockfile by the GitHub actions:

```r
renv::restore(lockfile = "renv/profiles/lesson-requirements/renv.lock")
```

Select option `2: Do not activate the project and use the current library paths.`

# Update the renv.lock and activate.R files locally with the workbench

```r
renv::upgrade() # check new version of {renv}
renv::update() # check for updated packages
```

```r
renv::status(lockfile = "renv/profiles/lesson-requirements/renv.lock")
?renv::status # find solutions to status
renv::install() # this may react to uninstalled packages, install and try again
renv::snapshot(lockfile = "renv/profiles/lesson-requirements/renv.lock")
renv::status(lockfile = "renv/profiles/lesson-requirements/renv.lock") # expect no issues
sandpaper::build_lesson() # confirm everything its ok
```

If a `renv` or any automatic update generates an unexpected change in any R outputs, then we should use that same PR to make the corresponding correction.

## `RcppParallel` action workflow error

After package updates, we present an error in the workbench actions/workflows. When the latest version in CRAN does not work, try referring to [RSPM](https://packagemanager.posit.co/client/#/repos/cran/packages/overview?search=rcppparallel) as the repository in the renv lock file, as tested in:

- https://github.com/epiverse-trace/tutorials/pull/112/commits/17faf73a726e05aeb97d8418802a23f900f84302
- https://github.com/avallecam/workbench-english/pull/1/commits/7d82eeee2e2e3e57024d6246cfe004e12f0b7eaf

# Add to general installation

```r
pak::pak("epiverse-trace/varnish@epiversetheme")
pak::pak("epiverse-trace/sandpaper@patch-renv-github-bug")
```

How to refer to local files within episodes? Here are examples of how we redirect to:
- [glossary](https://carpentries.github.io/sandpaper-docs/aio.html#learners) entries: [`[word](../learners/reference.md#word-tag)`](https://github.com/epiverse-trace/tutorials-middle/blob/c9f07409d4559e63fc1faf9766c6a8f9db0155d8/episodes/quantify-transmissibility.Rmd#L62)
- other episodes within the repository: [`[word](../episodes/name-of-episode.md)`](https://github.com/epiverse-trace/tutorials-middle/blob/c9f07409d4559e63fc1faf9766c6a8f9db0155d8/episodes/create-forecast.Rmd#L34) or `[word](name-of-episode.md)` (?)
- download a dataset: [`[data_cases.csv](data/data_cases.csv)`](https://github.com/epiverse-trace/tutorials-middle/blob/c9f07409d4559e63fc1faf9766c6a8f9db0155d8/episodes/create-forecast.Rmd#L243) this facilitates a [direct download, check](https://epiverse-trace.github.io/tutorials-middle/create-forecast.html#challenge-ebola-outbreak-analysis).

# About translations

- Avoid this type of wording: **"(...) using the `xxx::yyy()` function."** Instead, write: **"(...) using `xxx::yyy()`."** or **"(...) using the function `xxx::yyy()` to ..."**
- If using line brakes, please use [semantic line breaks](https://sembr.org/) and try to avoid non-semantic line brakes.
- Use multiple glosaries ([rOpenSci](https://translationguide.ropensci.org/es/specific_guidelines.es.html#glosario-es)) and Epiverse-TRACE) when using the babeldown workflow [tried in epiverse-trace/tutorials-early/pull/165]

## steps

- create the fork
- Go to Actions tab > Enable the workflows
- Got to workflows 01, 02, and 03 > Enable them manually
- go to settings > Pages > deply from branch > `gh-pages` > Save