Revamp documentation structure for discoverability and targeting

[zkamvar]

Given the experience of submissions to https://github.com/reichlab/variant-nowcast-hub, one of the main concerns is that it was not clear what packages modelers should use to support their submissions, partially because the documentation was not clear.

This highlights a need for broad restructuring of the documentation. Discussion from the 2024-11-13 meeting are as follows:

Zhian: Our main place for docs right now doesn’ evaluate code
Anna:
Could have a section of documentation that is a quickstart specifically for each user role (admin exists now, but what about toher groups like modelers, analysts)?
Package articles and vignettes
Readmes for packages, link out to specific package from main hubDocs
Harry: It might also help to have a super high-level introduction that lays out the broad strokes of how hubs work and the different roles that participants might play in hubs. This will help people learn which “getting started” spot would be most appropriate at any given time.
Zhian: Melissa’s diagram could inform this
Anna: could also pull from Kath’s higher level figure
There is a version of this in the manuscript; Nick will file an issue to add
Nick Reich (Nov 13, 2024, 9:28 AM): I agree! We’ve tried to do this here: https://hubverse.io/en/latest/overview/who-uses-hubverse.html
But we haven’t really created the detailed “Quickstart” guide for each kind of user.
Hochheiser, Harry (Nov 13, 2024, 9:29 AM): This is good. A figure or two might help make it even better. It also might help to add a definition of a hub and a summary of the workflow to the intro page.
Becky: We have heard feedback from modelers that it’s hard to know where to get started
Evan:
There is a vignette in the hubverse R package
Any documentation solution should be able to describe packages in multiple languages
Becky: also need something that says how to onboard a cloud hub (I lost track of this)
Nick: the menu on the left of the docs is too long. Could we collapse some subcategories? This would also give us room to add more headers to “external documentation”.
Harry: language-specific orientation might help. “If you are an R person, go here… If you are a Python person go here…”
Harry - consider moving away from the term “stakeholder”. See - https://doi.org/10.1007/s11625-024-01496-4, for example.
Zhian has volunteered to put together a plan for documentation. (not highest/immediate priority, but soon)