Pattern

On-Demand Information

Readers can have a non-linear experience of Data Cards so ensure that there is sufficient context maintained across the Card and the documents that it links to.

Additional information is helpful when it’s on-demand and with sufficient context.

Even the most technically adept user is unlikely to want to know everything about the dataset at very high fidelity. At the same time, unless they know exactly what they are looking for and what to expect in a linked document, a reader can easily get lost in a myriad of documents.

Pad links with short descriptive elements and summaries.

Always scaffold links with cues and summaries that help readers decide whether or not they need to click through. A cue is a short phrase that describes the document meaningfully, so readers know what to expect.

Use a summary to emphasize crucial information from the link that you don’t want readers to miss, and include any additional context that will help them understand the linked artifact better.

Link to artifacts that are contextually relevant to the Data Card section.

If you can link to specific headings or highlights in a larger document or sub-page in a website, even better! This is particularly useful if you’re going to be setting up a whole web page or readme document in a github repository that showcases your dataset.

The FIT400M Data Card embeds links within an explanation so they are well contextualized. This helps readers find advanced documentation about models if they need it. This helps readers find advanced documentation about models if they need it. "Paper" is a helpful cue that sets expectations of the kind of document and fidelity of content that the reader will encounter.

Not everyone may have equal access to linked documents or services.

Within an organization, not everyone may have access to linked documents or services. Seeking access can slow down the reader (who must ask for additional permissions), and can increase workload for producers. Alternatively, this can increase the amount of work necessary for readers to understand your dataset. Beyond your organization, not everyone may have access to documents which require registrations or have paywalls, or require special softwares to access.

Summaries can help readers understand why they can or cannot access restricted links, but should also communicate enough actionable material that your reader can still make a decision – or ask for more information.

Be mindful of linking to documents that switch context without reason.

These can interfere with a reader’s train of thought, cause them to switch tasks or deter them from the task at hand. If absolutely necessary, write a short description of the document ahead of linking it so readers can be prepared to switch contexts.

The More Inclusive Annotated People dataset utilizes labels identified from Google's Knowledge Graph API which requires an API key to use. Because the authors don't assume that readers have access to API keys, they link to additional descriptions of labels and introduce some labels in other relevant sections. This helps readers understand what knowledge graph IDs are without needing to use the API. However, the link directs to Knowledge Graph documentation – not support for API keys.