The description and summary are two key elements to add to any dataset or project to help others discover and understand them. For other documentation elements, see Documenting your data, and in this article, we'll dig in deeper to the how and why of the description and summary:
Datasets, projects, all the files in each, and all the columns in any structured data files have description fields associated with them. Descriptions are very short and serve as a quick reference for the item they describe. To edit the description for a dataset you can select Edit next to the description, Edit next to About this dataset, or navigate to the Settings tab:
To find more about adding descriptions to the files and columns within your dataset or project, see the Data dictionary article.
The summary is one of two documents created with a dataset or project. The summary is where all of the information about the origin of the data, why you created the dataset, further documentation of your work, etc. is found. Use the Summary section to tell your data's story. For example:
- Where did the data come from? Cite and link to your sources or include your details for a 'citation request'. Not only does this give credit where credit is due, but it helps other people evaluate the data's suitability for their needs.
- If you think a particular piece of context will be useful to others, add it.
- The best summaries cover the "who, what, where, when, why, and how" of the data.
- What's the data telling you? What would others be interested to know about it? What have others found using this data?
- If the data has associated data dictionaries or other documentation, upload it and then link to it from your Summary.
- Make it visually friendly with Markdown styling. It's easy to learn and goes a long way.
To write or edit the summary, select the Edit link in the top right corner of the summary window and you'll be taken to en edit window for the document Dataset summary in the workspace. The summary shown below was written with Markdown styling. There is a sidebar to the right of the summary window that is accessed by clicking the arrow in the upper right corner of the summary edit window will bring up a Markdown cheat sheet:
To see what your summary will look like formatted you can select the Preview tab:
Once you have saved your summary, if you used header formatting in it the right sidebar displays an outline of it with anchors to the various sections. In the example below the summary is very short, but the outline feature can be very useful for long summaries: