search

ices-eg / wg_WGTAFGOV

Working group on TAF Governance
https://community.ices.dk/ExpertGroups/WGTAFGOV/SitePages/HomePage.aspx
0 stars 1 forks source link

User handbook #14

Open colinpmillar opened 4 years ago

colinpmillar commented 4 years ago

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:

related issues

add reference to manifesto #1

odontaster commented 4 years ago

@colinpmillar @Milldaz @arni-magnusson

There are only 5 handbooks in ICES library:

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

odontaster commented 4 years ago

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

  1. What's TAF, link to manifesto (#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 #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 commented 4 years ago

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 commented 4 years ago

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 (#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 #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 commented 4 years ago

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 commented 4 years ago

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

colinpmillar commented 3 years ago

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

colinpmillar commented 3 years ago

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

colinpmillar commented 3 years ago

provide overview of user interface #35

nilsolav commented 2 years ago

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

colinpmillar commented 2 years ago

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

colinpmillar commented 2 years ago

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

nilsolav commented 2 years ago

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

cekv commented 2 years ago

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:

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

cekv commented 2 years ago

Work is ongoing to complete this task..

cekv commented 2 years ago

Work still ongoing.