Documentation Dialects

All scientific disciplines and communities understand that documenting their data makes it trustworthy and helps others use it with confidence. Many communities develop conventions for their documentation that enable sharing within the community, but can make it more difficult to share outside the community. Sometimes these dialects are called "standards" but, in the end they are all dialects of the same documentation language.


Evaluating documentation is critical for identifying good examples within a collection, for laying out a path forward and for recording progress as the documentation is improved. In the end, whether or not users can use and trust your data is the final evaluation. There are quantitative and qualitative steps that can be used as signposts on the way to trustworthy data.



Helping scientists and data providers understand how to improve their documentation involves understanding their requirements and identifying specific steps towards satisfying them. Explaining those steps with straightforward guidance, relevant community examples and rewards for moving forward are also important.