Instrument README Instructions🔗
Each HBCD Study instrument has a README page in the HBCD Data Release Docs - Study Instruments. SMEs use instrument-specific forms to review and update README content for upcoming and current data releases. Form links have already been provided for specific instruments, but all relevant links will be shared with SMEs in the near future.
Quick Start🔗
- Open your instrument- AND release-specific form
The form will be pre-populated with the instrument's existing README information, including a link to the latest README on the site (or draft README on a dev version of the site for a future instrument). - Review and update the content
Write for an external research audience, focusing on information researchers need to understand and use the data. - Submit changes as needed
You do not need to finish the entire form before submitting. The form will save your work if you close it prior to saving changes, but we still recommend that you submit whenever you need to step away for a while. - Continue revising as needed
README documentation can be updated on a rolling basis, including corrections to current release documentation. - Designate a single form submitter
This is recommended particularly during active update periods as simultaneous form submissions may overwrite one another!
Note that not all changes may be possible to make via this form alone (such as larger reorganization, more complex formatting, etc.). Contact the administrators for assistance.
Key Resources🔗
- README template: displays structure of each page and purpose of each section
- Published READMEs: Review current README pages for examples of content and level of detail to include under Study Instruments
Content Guidelines🔗
Keep the audience in mind!! Avoid references to internal workflows, documentation, data management systems, or study operations unless they are necessary for understanding or using the released data. Imagine what information you would find helpful if you were an external researcher wanting to use this dataset.
Draft longer sections outside the form. For sections such as Instrument Details, consider entering an initial draft in the form and then doing substantial editing or collaborative review outside the form before submitting the polished version. You should generally be able to copy and paste text directly from platforms such as Google Docs into the form and your formatting (e.g. embedded links, bold/italics, etc.) should be preserved.
Keep formatting simple. Much of the formatting is pre-set to maintain consistency across README pages. However, please use bold, italics, links, lists, etc. to improve readability as needed. Note that pre-populated field text will be in Markdown format. We are working on solutions for this, but in the meantime, if you're unsure of how to update the text, here are temporary solutions to restore the rich text:
- Copy the text directly from the README on HBCD Docs into a Google doc, make your edits, and copy-paste the final text back into the form
- Copy the form contents into a Markdown to rich text converter, replace the form field contents with the rich text version, and make edits from there
Need help?🔗
Please email Lucille Moore (lmoore@umn.edu), Stephanie Averill (saverill@ucsd.edu), and/or Jen Zink (jzink@lassoinformatics.com) if you have any questions about this form or need guidance!
Appendix🔗
README Workflow & Information Storage🔗
Each instrument README sources most or all of its contents from a central Airtable repository that stores all instrument README information. This repository is updated and populated via external forms, with a separate link provided to SMEs per instrument. When you load a form, all of the existing information for that instrument prepopulates the fields.
