add complementary writing guidelines

[avallecam]

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

Ideas in #80

---

In:

tutorials/CONTRIBUTING.md

Line 132 in ad7dd94

### Writing guidelines

For Workbench novice users:

• Follow the steps to create a new 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:

• Render lesson with sandpaper::build_lesson(). 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 or tracelac theme).
• Create a new episode:
  • run sandpaper::create_episode_rmd(title, add) or
  • make a copy of the file or callouts in episodes/template.Rmd
• Read about How to edit the workbench.
• Do not include code lines to install packages like install.packages() or pak::pak() inside an episode file. We rely on {renv} via {sandpaper} 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 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 using a syntax like [^1]
• Read about the core workbench style guides for figures, divs, and line length.
• Read issues labelled with to-keep read new features we want to keep in this repo.
• When creating your PR, resolve conflicts locally using git rebase. This:
  • Allows running GH-actions to evaluate if the contribution passes all the validation checks.
  • Facilitates PR review (ref)
• Use {lintr} addin to "Lint current file" from Rstudio or other editors.
  • 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.
• For self-created figures we prefer a .png format, which is more appropriate to be displayed in modern web browsers. 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
• Use full package 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 use {webshot} package to print {Diagrammer} and {visNetwork} outputs #98 [now evaluating to consider mermaid https://github.com/Consider using mermaid diagrams instead of graphviz tutorials-late#46]
• Add tables using a markdown table generator: https://www.tablesgenerator.com/markdown_tables
• Given agreement in using explicit namespace to all functions Use explicit namespacing in reports episoap#91 we need to unlock this check in lintr warning from {lintr} workflow in [namespace_lintr] #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 feature in the rendered website.

Add in the Maintainers:

• Read about the automated update of workflows and package cache.
• Create a WIP Issue defining the branch name, the task in the roadmap, packages, and the contributor assigned to it.
• Read about how to create CITATION file for this type of repository.
• Update the "minimum supported version" annually to the setup file. This follows the R version support tidyverse policy.
• 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 then submit to Epiverse-TRACE community following steps in Zenodo > Submit to community. Paste Zenodo DOI on README.

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

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.

Add to general installation

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 entries: [word](../learners/reference.md#word-tag)
• other episodes within the repository: [word](../episodes/name-of-episode.md) or [word](name-of-episode.md) (?)
• download a dataset: [data_cases.csv](data/data_cases.csv) this facilitates a direct download, check.

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 and try to avoid non-semantic line brakes.
• Use multiple glosaries (rOpenSci) and Epiverse-TRACE) when using the babeldown workflow [tried in add code to generate a mixed glossary from rOpenSci and Epiverse-TRACE tutorials-early#165]

[avallecam]

@amanda-minter @Degoot-AM I'm updating here some extra writing guidelines to include later in the CONTRIBUTING file. If you have any questions or additional suggestions, please share them here.