Organize documents around workflows

[bwalsh]

Jordan Lee
10:00 AM
In terms of the flow of the docs (not the functionality): I like that there are many tools/commands that cover different use cases, perhaps framing these tools into a workflow. Currently it feels like a page to search for key words (ex. “pull metadata” “push metadata”) rather than a step-wise workflow. an example being the step to convert fhir to tabular data is then followed by convert tabular data to fhir, where a user won’t need to do both of these conversions back to back (taking a second pass through all steps in the doc could be beneficial). this comment is regarding this:
https://github.com/ACED-IDP/aced-idp.github.io/blob/main/docs/workflows/metadata.md

[bwalsh]

@jordan2lee Can you sketch out more detail (an outline or diagram)?

[jordan2lee]

First a few comments on areas of improvement:

• it's unclear in which scenarios a user should use "integrate your data" section. I assume it is only in "i want to append metadata to already existing metadata" but doesn't need to be followed in "i have metadata for a project that doesn't already have metadata" because if this was the case then the user just needs to run the section "create metadata"
• make it more clear that the user doesn't have to run both sections "create metadata" and "retrieve existing metadata" if they are working with a project that doesn't already have metadata
• the section "integrate your data" suggests that users are preparing their data for upload to aced, thus would not need to "convert FHIR data to tabular form". we can remove this section and place it into a section about downloading data (users can taken the fhir data stored with ACED and then change it to a tabular view). Note do still keep the convert tabular data to fhir but add language to explain this step requires user data to be in x, y, and z format in order to run "from_tabular"

[jordan2lee]

Below is a suggested outline:

---

Creating and Uploading Metadata

Create New Metadata

If no existing metadata uploaded to the project, then follow this section...

Retrieve Existing Metadata and Add to it

If there is existing metadata uploaded to the project then follow this section...

1. How to retrieve exiting metadata
2. How to append metadata to it

Integrate your data (metadata?)

Add a sentence to clarify if this "data" is the metadata or the actual data that we are reformatting into FHIR format

1. Convert your tabular data into FHIR format
2. Validate your data
   Add wording about how this command ensures your data is in the appropriate FHIR format

Publish the Metadata

View the Files

[jordan2lee]

other than that, the outline structure looks good