Documentation
Add guidance on documentation, reproducibility & transparency, oh my!
This is intended to be a living document and providing documentation is extremely important.
Remember - if your project or process is not well-documented to the point of being largely reproducible - it’s incomplete!
Why Document?
Documentation is a critical to improving transparency, ensuring when roles or positions change data and information is not lost. Clear documentation also allows us to pick up where we left off, or easily transition data projects from one team to another. Clear documentation in our data workflow can help identify areas of improvement in workflows and paths forward. Creating and documenting can also make your project more manageable, and over the long-term, documentation increases transparency and equity.
What do we Document?
Detailing where data or projects live and whether they’re posted to internal or external websites.
Naming files deliberately
Data Dictionary
Document code through comments
Tools Available to Support Documentation:
Schema.org – Promoting common data structures on the internet
Accessibility tips using Markdown (Smashing Magazine)
Writethedocs.org, plus a piece on documenting for beginners
Templates for documenting on GitHub (e.g., on a ReadMe)
GitHub projects best practices