Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update documentation #1

Merged
merged 4 commits into from
Sep 1, 2023
Merged

Update documentation #1

merged 4 commits into from
Sep 1, 2023

Conversation

abought
Copy link
Member

@abought abought commented Jun 27, 2023

Purpose

The user facing documentation is severely out of date, and many API examples do not run as written. To support upcoming external pentesting (as well as, you know, everyday users), this contains a number of updates.

Preview: https://topmedimpute.readthedocs.io/en/fix-2023-doc-updates/getting-started/

Changes to docs

  • Add FAQs for common user questions such as sample size, security questions, etc
    • Explicitly mention the new US Govt ATO
  • Add more guidance for data preparation
  • Aim all contact questions at helpdesk and update staff list
  • Fix available API params and include missing options
    • Update API examples to run as written (both curl and python versions) + update example payloads to reflect current structure
  • Hide information that does not apply to TIS
  • Hide docker and "create reference panels" documentation, to reflect that TIS is a more focused service
  • Remove reference panels not supported on TIS; replace with link to MIS docs
  • Remove references to HLA imputation. It's pretty cool, but only present in MIS. Documenting it for our service is confusing.
  • Add readthedocs config files (mandatory as of Sept 2023)
    • Fix mkdocs syntax to reflect feature changes/ drift.

Other notes

I have reinstalled a missing RTD webhook that has prevented new doc builds from being published for 2 yr. Once this PR is approved, we should also update the branch that RTD uses for the public docs --> release. (the previous branch no longer exists)

Future additions

* Add FAQs for common user questions such as sample size, security questions, etc
* Add more guidance for data preparation
* Aim all contact questions at helpdesk and update staff list
* Fix available API params and include missing options
* Update API examples to run as written (both curl and python versions) + update example payloads to reflect current structure
* Hide docker and "create reference panels" documentation, to reflect that TIS is a more focused service
* Remove reference panels not supported on TIS; replace with link to MIS docs
* Add readthedocs config files (mandatory as of Sept 2023)
@abought
Copy link
Member Author

abought commented Jul 11, 2023

Reminder to self: Albert (may??) have edits in flight on this branch.

Once the branch is stable, we should update our user instructions link to point to the TIS documentation. Presently the UI is sending people to the wrong place.
https://github.com/statgen/imputationserver/blob/release/files/minimac4.yaml#L5

Screen Shot 2023-07-11 at 2 28 48 PM

@abought
Copy link
Member Author

abought commented Aug 31, 2023

Added Jonathon's notes about GT field, since we've seen the error in the wild.

It's been two months since this PR was first created. Pinging for status: ok to merge and make additions later?

Signoff: build error is a known issue with an upstream vendor that removed access to dependencies. This PR only edits text files, so it doesn't break mergeability for this PR.

(honestly, it only ran CI because I forgot to add [ci skip] in the commit message)

@abought abought merged commit 5bb17b6 into release Sep 1, 2023
@abought abought deleted the fix/2023-doc-updates branch March 27, 2024 20:00
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants