User handbook

[colinpmillar]

summary

Examples of other user handbooks are the SMARTDOTS ones listed here: ICES User Handbooks

potentially split this out as it develops

task list

Do be developed:

• @odontaster to investgate other handbooks
• Agree on general structure of handbook

related issues

add reference to manifesto #1

[odontaster]

@colinpmillar @Milldaz @arni-magnusson

There are only 5 handbooks in ICES library:

• Smartdots software, very specific on the use of this software, screenshots etc
• Smartdots web api, technical description
• Smartdots web api manual
• Guidelines for VMS data call, very descriptive on the step by step, R installation and so on
• Best practice for data management

I don't see a clear common structure to all of them.

[odontaster]

Suggested structure for TAF handbook, as points in the table of contents:

1. What's TAF, link to manifesto (Manifesto completion #1 ), general description, app, github etc
   Also here information on roles, data policy etc

2. Types of repositories according to advice products, linked to issue Define a list of repository types and formats #13
   2.1. Stock assessments
   2.2. Other advice products, Fisheries Overviews, other?
   2.3. Data products feeding into the other two, f.ex. Survey indices?
   2.4. RDBES, maybe for a future update of the handbook?

3. User set up, log in etc.

4. Repository setup, who, how, where

5. Repository structure (link to youtube tutorial)
   5.1. Bootstrap, DAT, BIB etc
   5.2. Data
   5.3. Model
   5.4. Report

6. Useful tools
   6.1. icesTAF package
   6.2. other?

7. Annotated examples, links to repos
   7.1. Assessment (maybe two of different categories or complexity)
   7.2. Fisheries Overview, with external data for instance
   7.3. Indices from Eggs & Larvae, coming from one of the EGs repositories.
   7.4. RDBES estimations, in the future

What do you think? how should we move forward?

[colinpmillar]

I think that's a great start and great to move forward. We also have a wiki page: https://github.com/ices-taf/doc/wiki that we can either link to, or steal material from and combine into one doc. Will leave that for later.

I thought we could write it as a Rmd document:
https://github.com/ices-eg/WGTAFGOV/blob/master/user_handbooks/user_handbook.Rmd

I ahve set up a github action to build the html file whenever there is a commit, so no need to push your locally built html file.

[arni-magnusson]

Thanks for pointing the way forward, Adriana, this looks great! We could merge Users and Repositories into one section, and have the icesTAF package at the section level:

1. What is TAF
   1.1 General description and Manifesto (Manifesto completion #1)
   1.2 The TAF Server (web app)
   1.3 icesTAF (R package)
   1.4 TAF Repositories on GitHub

2. Types of repositories according to advice products, linked to issue Define a list of repository types and formats #13
   2.1. Stock assessments
   2.2. Other advice products, Fisheries Overviews, other?
   2.3. Data products feeding into the other two, f.ex. Survey indices?
   2.4. RDBES, maybe for a future update of the handbook?

3. Users and repositories
   3.1 User set up, login, etc.
   3.2 Repository setup, who, how, where

4. Repository structure (link to YouTube tutorial)
   4.1 The boot procedure, initializing software and data
   4.2 Scripts: data, model, output, report

5. The icesTAF package
   5.1 Core functions: taf.bootstrap, sourceAll
   5.2 Get started: taf.skeleton, draft.data, draft.software
   5.3 Working with tables and figures

6. TAF scripts
   6.1 Reproducible code, relative paths, platform independence
   6.2 Writing results into the working folder
   6.3 Verifying with taf = TRUE

7. Annotated examples, links to repos
   7.1. Assessment (maybe two of different categories or complexity)
   7.2. Fisheries Overview, with external data for instance
   7.3. Indices from Eggs & Larvae, coming from one of the EGs repositories
   7.4. RDBES estimations, in the future

[colinpmillar]

Wondering if need a section on the icesTAF package...

The logic and workflow is heavily tied to the R package at the moment, so it doesnt make sense (to me) to present this in its own section, probably better throughout the document. We write about it in the opening section "what is TAF", then all the code examples throughout will use the icesTAF functions. The whole docuent is essentially an extended guide to the R package and the web interface.

We could include an appendix, But then there is also a risk of the section becoming out of date. If functions change, then we will have to update the package, package documentation and the TAF user guide. Probably more streamlined to simply refer to the package documentation - i.e. https://rdrr.io/cran/icesTAF/

On a side note, If we move to bring in other languages, we might have each code example with a tab for R, python, etc. We might even have a tab for different versions.... (throwing out ideas)

[colinpmillar]

Do you think we can develop this as a wiki page, and produce a pdf / html doc from it at a later date?

[colinpmillar]

@ghislainices suggests thinking of ways to involve the community in the development of the user handbook. How can we move this forward.

[colinpmillar]

Agree to set up a subgroup of users to take this forward.

[colinpmillar]

provide overview of user interface #35

[nilsolav]

Retructure this task and collating it with the other documentations tasks.

[colinpmillar]

There are some ouputs from workshops that could be added to the wiki:

• example simple repositories
• turn each step into a wiki page?

[colinpmillar]

Documentation page listing each assessment model and the repos showing the code for each.

[nilsolav]

Add the list of TAF examples for different models to the wiki page and advertise it.

[cekv]

The consensus is to use the TAF doc GitHub wiki page as a user handbook, instead of a publicised ICES handbook.
https://github.com/ices-taf/doc/wiki
The wiki will include:

• Teaching/learning material
• How to get started
• Creating a TAF analysis
• Bib entries
• Example data records
• And much more...

This will be a fluid handbook where code will change and other aspects of TAF added.

[cekv]

Work is ongoing to complete this task..

[cekv]

Work still ongoing.