Data Ab Initio

We’re continuing our tour of strategies for how to make your research data more accessible by discussing headings. These may not seem generally applicable to data, unless your data is text, but stick with me because headings actually are important to data’s accessibility.

Headings, or section headers, are the short snippets of text that you can use to label sections of a text document. Often these appear as text with a larger, bolded font and sometimes they have section numbers.

What you might not know is that many text file formats support explicitly marking text as headings at discrete levels. One of the benefits of using marked headings is that you can automatically create a table of contents for your document. With respect to accessibility, headings help screen reader users navigate a document more easily by jumping between headings (instead of being forced to read all of the text between the start of a document and the target heading before you get to the content of interest).

Headings come in multiple levels, usually levels 1-6, and nest like a tree. Documents should start with heading level 1, typically used for the document title, and proceed through lower subheading levels as fits the content. A rule of headings is to never skip a level on your way down the tree; so you would never jump from a heading level 1 to a heading level 3 without heading level 2 in between.

So if headings are key to adding structure to text documents, why are they important to a dataset’s accessibility? The answer lies with the data’s documentation. Truly reusable data must come with documentation and the accessibility of that documentation is an important component of the data’s overall accessibility. Since text is the most common format for data documentation and headings make text documents more accessible, therefore headings matter to a dataset’s accessibility.

In addition to accessibility considerations, there’s actually evidence that using headings in data’s documentation helps with reusability too. Koesten et al. studied 1.47 million datasets from 65,537 repositories on GitHub, and found that “the most reused datasets also seem to have more detailed README files” (README is a common type of data documentation and one that is natively supported on GitHub via README.MD Markdown files). The authors found that the most reused datasets had longer README files with more words in them and also contained more headers, indicating that the documents had more structure. Overall, the research showed the greater data reuse was correlated with more detailed documentation, a component of which was added documentation structure through headings.

All of this evidence is why I’m starting to rethink the TXT file’s role in dataset documentation. More documentation is better for reuse and more text in documentation necessitates using headings for easier navigation. However, headings are not supported in TXT files. GitHub uses Markdown for its default README format and this clearly has a benefit for not only accessibility but also reusability. I’m not sure what is the best file format for README files, but I do know that it should support headings.

I encourage you to use built-in headings in your preferred text editing software, whether the application is for data or not. Headings take an extra couple of seconds to mark but come with lots of benefits. For data, I have a sense that we don’t regularly use headings in data’s documentation and I think that should change. I hope this blog post makes you consider using headings in your documentation the next time you share your data.

Today, I want to continue to discuss various ways to make research data more accessible. While there are specific accessibility recommendations for specific types of data files, such as recommendations for accessible and reusable spreadsheets, we’re going to focus on something more general today: plain language.

Plain language is a clear way of writing that makes your content easier to understand. Plain language doesn’t necessarily apply to research data (as you shouldn’t alter data), but is a good strategy for documentation, where you have direct control over what you write. The idea is that if you write your documentation more clearly, people will better understand your data and can more easily reuse it. Using plain language is also an accessibility issue, as it helps people with various cognitive disabilities better understand written content.

So what does plain language look like? Plain language recommends simplification wherever possible. Some common recommendations for plain language include:

• Write the most important information first;
• Keep sentences short and direct;
• Keep paragraphs short;
• Break content into sections and use headings;
• Avoid jargon;
• Define acronyms and abbreviations;
• Use bullet pointed lists, where possible.

You can adjust your writing to your audience and use research-specific terms, but remember that some researchers in your field may not be native English speakers. So plain language for research documentation should balance using clear and direct words against field-specific terminology.

Plain language also involves writing at a lower reading level, typically no higher than a lower secondary education level (WCAG 2.2, Criterion 3.1.5). Even with the ability to adjust your writing to your audience, assuming a lower reading level will make your writing more accessible to everyone, even those without disabilities.

Let’s look at an example of plain language. Let’s start with the sentence: “based on the state of the local flora and where we are in the growing season, I recommend ceasing the collection of samples.” A plain language version of that sentence is: “do not pick the flowers.” The second sentence is much clearer and more direct and means roughly the same thing.

Writing in plain language is an art and takes practice. But I encourage you to think about plain language the next time you create research documentation so as to make your documentation (and thus your research data) as accessible as possible.