User Guide documentation

[floradanna]

Hi all, I was wondering if the Community Workers could improve the current FAIRDOM-SEEK User Guide. I noticed that few features are missing and that some items are listed without a clear order.

I would like to propose some changes, such as grouping items by the categories as shown in "Create/Browse", that are Yellow Pages, Experiments, Assets, Samples etc...

Here there is a first draft, please let me know what's your opinion.

USER GUIDE

YOUR PROFILE

• Registering in SEEK
• Logging into SEEK
  • Logging into SEEK via ELIXIR AAI
• Managing your account
  • Managing your identities/alternative login methods
• Editing your profile
• Favourites (missing)

YELLOW PAGES

• Browsing content
• Creating and managing your own Programmes
• Creating a Project
• Joining a Project
• Project Dashboard
• Viewing Project in Single Page (draft ongoing)
• Specialist user roles and their capabilities
  • Programme administrator
  • Project administrator
    • Assign people to Project roles
    • Flag when a person becomes inactive in a Project (still coming soon?)
  • Create Organisms
  • Create Profiles
  • Create Institutions
  • Add and remove people from a Project
  • Asset housekeeper
  • Asset gatekeeper

EXPERIMENTS

• Generating the ISA structure
  • Creating an Investigation
  • Creating a Study
    • Investigation details
  • Creating an Experimental assay
    • Assay Type
    • Technology Type
  • Creating a Modelling analysis
    • Biological Problem Addressed
• ISA Overview Graph
• Experimental assays and Modelling analysis
  • Study
• Designing experiments in Single Page (draft ongoing)
  • Creating an Investigation in Single Page
  • Creating a Study in Single Page
  • Creating an Assay in Single Page
  • Creating samples in Single Page
• Export ISA (to do)
• Making an Investigation, Study or Assay citable
  • Making public
  • Snapshotting
  • Creating a Research Object
  • Assigning a DOI

ASSETS

• Adding assets (data, models, SOPs, publications) to SEEK
• Data Files
  • Data file wizard(https://docs.seek4science.org/help/user-guide/data-file-upload-wizard.html)
• Model (missing page) --> available in API documentation (https://fairdomhub.org/api#tag/models)
  • Simulate a model on JWS Online
• SOPs
• Publications
• Collections
• Document
• Workflow
• File template
• Placeholder
• Creating new asset versions
  • Comparing two versions of a Model

SAMPLES

• Samples
  • Create a Sample Type
  • Create a Sample
  • Legacy Biosamples
• Creating samples in Single Page (link to subpage above)
• Templates (to do)
  • Sample Type in Single Page
• Query Samples (to do)
  • By Sample Type
  • By Templates

ACTIVITES
Events (link below?)
Presentation (missing)

GENERAL ATTRIBUTES AND LINKS

• General attributes and links (name it “Generic linking variables in SEEK”)
  • Title
  • Description
  • Projects
  • Sharing
    • Bulk changing of sharing permissions
  • Tags
  • Organisms
  • STRAIN???
  • Attributions
  • Creators
  • Experimentalists
  • Events
  • PRESENTATION?
  • Discussion channels (missing)
• Licenses

INTEGRATIONS

• Using SEEK with openBIS
• Using Copasi in SEEK

USER GUIDE FOR API

• API Introduction

CONTRIBUTE

• Reporting a bug or feature request
• Contributing to these SEEK Documents

[floradanna]

Missing information could be taken from API documentation: https://fairdomhub.org/api#tag/models

[OlgaKrebs]

... also "publishing with SEEK" can be an extra docu folder and not just part in ISA(EXPERIMENT) forlder - user very often ask where to find this

[floradanna]

Indeed, the "publishing" is missing or not very visible. By publishing, you mean

• make an item public (I have a doubt: is setting sharing permission as Visible to Public the same of clicking "publish" to create DOI?)
• make snapshot
• assign DOI
  Correct? This is indeed described only for ISA, but it is possible for any items.

We could add it to:
GENERAL ATTRIBUTES AND LINKS

• General attributes and links (name it “Generic linking variables in SEEK”)
  • Title
  • Description
  • Projects
  • Tags
  • Organisms
  • STRAIN???
  • Attributions
  • Creators
  • Experimentalists
  • Events
  • PRESENTATION?
  • Discussion channels (missing)
• Licenses
• Sharing
  • Bulk changing of sharing permissions
• PUBLISHING ITEMS
  • Making an Investigation, Study or Assay citable
  • MAKING ITEMS CITABLE

[OlgaKrebs]

what is about having sharing and publishing in one "big" folder with a title "Sharing Permissions for your data : from privat to public" and inside 1. sharing 2. bulk sharing 3. publishing with and without DOI 4. 4. RO & Zenodo 5.licensing

[floradanna]

Yes, it could be a good structure.

I don't find any documentation about RO and Zenodo. Is it somewhere I don't know about? If it is missing, could you write the "step by step" process to generate RO and Depositing in Zenodo? You can either do it GitHub pages or in a google doc and share the link here.

[abecam]

So related to that, the document for the short description and links to documentation within Seek is here: Short description for Pop-Up information
I sometime provided the description from the documentation (together with the link to it then) and/or from the API doc (so without link, as there are no further information there).
Some items are still without anything.

[floradanna]

@abecam Should we add the missing content to the doc?

[abecam]

Yes, and don't hesitate to edit (also as there are 2 choices when there was entry in both the documentation and the API doc).

[floradanna]

We had to provide documentation for DataHub urgently for our test instance, I re-arranged and added content to the User Guide here: https://datahub.help.elixir-belgium.org/test/help/user-guide/index.html

We could discuss what changes can be merged and made available in the main code and what needs to be edited further.

[floradanna]

Structure in User Guide pages

[rabuono]

Highlighting a comment:
Having the guide pages without basic context and definition of concepts might confuse some users.

I think that keeping the user guides separate from the basic concepts, as it is in FAIRDOMhub now, is a good idea. One can present the basic concepts above the user guide, but is not committed to having concepts that don't apply to the instance in the help section

[stuzart]

I've created a branch for you here: https://github.com/seek4science/seek/tree/gh-pages-refactor

gh-pages-refactor

[stuzart]

I've created a branch for you here: https://github.com/seek4science/seek/tree/gh-pages-refactor

gh-pages-refactor

It turns out I got my wires crossed and this branch isn't needed, so will be deleted.