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

Add more explicit mentions of documentation #292

Open
fasterius opened this issue Dec 3, 2024 · 1 comment
Open

Add more explicit mentions of documentation #292

fasterius opened this issue Dec 3, 2024 · 1 comment

Comments

@fasterius
Copy link
Collaborator

Something we mention briefly in the materials is documentation, but we don't go into much detail regarding it. We do talk about it in e.g. the Git, Quarto and Jupyter material, but given the discussions in #289 (comment) I think we can be more explicit about this.

One solution would be to first be more explicit throughout the materials in general that documentation is indeed a thing the students should be thinking about. This would entail going through the material and adding mentions where applicable. The second part would be to add explicit mentions in the lectures as well - I'm thinking in the Quarto/Jupyter lectures as well as the final putting-it-all-together lecture.

Another solution would be writing a whole new page just for documentation, but I'm unsure where that would fit into the schedule.

Other ideas?

@mahesh-panchal
Copy link
Contributor

I think a section on documentation at the end, for binding it all together, would be a useful addition.
The paper The five pillars of computational reproducibility: bioinformatics and beyond has a section on documentation that could be expanded upon, and in particular includes some links to check lists which students could use as exercise material.

MDAR: https://osf.io/2k3va/

The MDAR stuff might be too much, but making a smaller checklist like README, compute resources used, data accessibility, etc would be useful to students.

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

No branches or pull requests

2 participants