Researchers often create scripted actions that operate on released outputs, for example, to create tables or charts for publication. The scripted actions operate on released outputs specifically, such that the scripted actions can be run outside a secure environment, allowing faster iteration.
23 established that researchers can, in principle, use released outputs in Codespaces. The new "How to use released outputs in a Codespace" page should contain information about how they can, in practice, do so.
The page should describe how researchers can drag-and-drop or upload released outputs to Codespaces; and download tables or charts from Codespaces.
The page should reassure researchers about security: Only the Codespace's creator can access the Codespace, unless the Codespace's creator enables Live Share or unless the Codespace's creator starts a service on a different port.^1
The page should refer to the "Datasets used" section of the "Policies for Researchers" page. (This section will soon be updated to make the references to "webinar" and "email" examples, rather than restrictions.)
The page should explain why researchers should not commit released outputs, tables, or charts to the repo.
Whilst the instructions in the how-to will also apply to published outputs, very few released outputs are published. To avoid confusion, the how-to should focus on released outputs.
The new page should avoid:
screenshots. These need to be updated regularly and are more suited to a tutorial.
a discussion of reproducibility (e.g. whether to add scripted actions to project.yaml and whether to add/update packages in the dev container environment). Reproducibility is a large topic; too large for a how-to.
If you're unsure what makes documentation good, then read:
Researchers often create scripted actions that operate on released outputs, for example, to create tables or charts for publication. The scripted actions operate on released outputs specifically, such that the scripted actions can be run outside a secure environment, allowing faster iteration.
23 established that researchers can, in principle, use released outputs in Codespaces. The new "How to use released outputs in a Codespace" page should contain information about how they can, in practice, do so.
The page should describe how researchers can drag-and-drop or upload released outputs to Codespaces; and download tables or charts from Codespaces.
The page should reassure researchers about security: Only the Codespace's creator can access the Codespace, unless the Codespace's creator enables Live Share or unless the Codespace's creator starts a service on a different port.^1
The page should refer to the "Datasets used" section of the "Policies for Researchers" page. (This section will soon be updated to make the references to "webinar" and "email" examples, rather than restrictions.)
The page should explain why researchers should not commit released outputs, tables, or charts to the repo.
Whilst the instructions in the how-to will also apply to published outputs, very few released outputs are published. To avoid confusion, the how-to should focus on released outputs.
The new page should avoid:
project.yaml
and whether to add/update packages in the dev container environment). Reproducibility is a large topic; too large for a how-to.If you're unsure what makes documentation good, then read: