opensafely / opensafely/documentation
Extending output checking guidance to make requests easier to review
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 48
- Forks
- 10
- Avg merge
- 2d 19h
- Merged PRs (30d)
- 17
Description
Below are some behaviours that make output checking more difficult that we should discourage in the docs.
-
Incomplete context. Some of the context descriptions I see only make sense if you have prior knowledge about the project. We should extend this list or context requirements to make it clear that the context should make the request understandable to someone not familiar with the project
-
Not using file groups. Some requests group all files into a single group and then write describe groups of files within a single, long context. As a reviewer, this means I have to describe what subset of files i'm referring to when I make any comments. If the files were appropriately grouped in the first place, this would be obvious.
-
Producing wide tables that don't have to be wide. Wide tables where all of the columns don't fit into view are difficult to review. Sometimes this is unavoidable, but there are times where it's not necessary. For example:
count_numerator_age_18_39 count_denominator_age_18_39 count_numerator_age_40_59 count_denominator_age_40_59 count_numerator_age_60_plus count_denominator_age_60_plus count_numerator_sex_F count_denominator_sex_F count_numerator_sex_M count_denominator_sex_M count_numerator_imd_1 count_denominator_imd_1 count_numerator_imd_5 count_denominator_imd_5 value 120 1000 340 2500 510 3000 480 3200 490 3300 95 800 140 900 This is easier to check (visually, and with the built-in summary stats) if it's structured like:
demographic category count_numerator count_denominator age 18–39 120 1000 age 40–59 340 2500 age 60+ 510 3000 sex F 480 3200 sex M 490 3300 imd 1 95 800 imd 5 140 900
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with the linked requesting-file-release page and read the “Context and controls” section. Update the guidance to cover understandable context, appropriate file groups, and avoiding unnecessarily wide tables, using the examples in the issue; done means reviewers can find all three recommendations in the documentation.
Written by the indexing model from the issue text.
Assessment
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 78/100