DARIAH-Campus Style Guide

Why Do We Need a Style Guide?

Establishing and following the style guide for DARIAH-Campus is important as a way of ensuring:

• Clarity and Conciseness: Content should be written clearly and concisely, avoiding jargon and complex language.
• Visual Consistency: Resources should adhere to a uniform visual style, including guidelines for fonts, use of colours, and layout.
• Content Structure: Materials should follow a structured format, with clear headings, subheadings, and sections to facilitate easy navigation.
• Citation and Attribution: Proper citation and attribution practices should be followed to acknowledge the contributions of others and maintain academic integrity.

DARIAH-Campus is currently managed using a content management system (CMS) that sits on top of a GitHub publishing framework.  This allows for version control, and also for editing via both direct Git access, and the CMS.  The full instructions and user guide for how to edit and publish resources on DARIAH-Campus can be found elsewhere on these DARIAH-Campus ‘Documentation’ pages, and therefore will not be reproduced here. 

The use of the CMS already provides a level of consistency across the resources hosted on DARIAH-Campus in terms of the overall structure, required metadata elements and visual uniformity (utilising pre-chosen fonts, colours and design elements which maintain a cohesive visual style across all materials).  However, authors may still need additional instructions to ensure the highest quality and usability of the resources, especially in terms of the writing style (tone, language and clarity, spelling conventions, etc.) and accessibility. 

General House Style

This section covers the general house style across the entire DARIAH-Campus platform.  Specificities of the different resource types are dealt with separately below.

Authors, Contributors and Editors

Authors are a required field for all resources. However, if the resource requires a distinction between the different types of contribution to the creation of a resource, there is also the option of using the ‘contributing authors’ and ‘editors’ fields as appropriate.  Do note, authors and contributing authors are listed together in the automated citation in the order in which they are entered into the CMS.  Editors are listed separately.  An example of this can be seen below:

All authors must be accompanied with a profile photo.  This should be in a 1:1 (square) dimension, in either JPEG or PNG format, and no smaller than 150 x 150 pixels (approx 17KB in file size), no larger than 500 x 500 pixels (approx 300KB file size).

Titles 

The capitalisation of titles of resources follows the APA style guide quite closely. That is:

“In title case, major words are capitalized, and most minor words are lowercase. In sentence case, most major and minor words are lowercase (proper nouns are an exception in that they are always capitalized).

• major words: Nouns, verbs (including linking verbs), adjectives, adverbs, pronouns, and all words of four letters or more are considered major words.
• minor words: Short (i.e., three letters or fewer) conjunctions, short prepositions, and all articles are considered minor words.” (APA 7th Edition)

Language and Standard Language Use

DARIAH-Campus provides multilingual content. With regards to English, the platform is agnostic as to which standard form of English can be used (e.g. British English, American English, Indian English, etc.). However, it is important to be consistent throughout a single resource.  Exceptions to this are when quoting from a source that uses a different standard form, such as if one is using British English throughout a resource, but quote from a resource that uses American English spelling.

To help to identify the differences between British forms of English and American English standards, the ‘Eleven Writing’ blog offers a comprehensive guide.

Heading Hierarchies

It is important to ensure that the hierarchies of headings remain consistent to enable better accessibility and support screen-reading technologies.

For that reason, the titles of all resources form the ‘Heading 1’ position.  When adding additional headings to the content, they should therefore start with ‘Heading 2’ and be structured in subsequent sub-headings accordingly. 

Typical ‘Heading 2’ items include:

• Introduction
• Learning Outcomes
• Any subsequent section headings (sub-headings continue the hierarchy structure with heading 3 or 4).

Ideally, no subheading should go below ‘Heading 4’.  If ‘Heading 5’ or lower has been used, consider whether that information can be merged into a ‘Heading 4’ or higher paragraph.

Images and Tables

Images can be added to any resource on DARIAH-Campus. The standard width of the DARIAH-Campus content column is 800 pixels. Images are automatically aligned to the centre, therefore any images smaller than 800 pixels will by default be sized up by the CMS to fill the space.

All images must be accompanied by ‘alt text’ (alternative text) to enable greater accessibility (see ‘Accessibility’ section below), and a caption.  When captioning images or figures, the caption should appear below the item.

Tables should include a heading row, with the text formatted in bold.  The text within the table should be formatted as the same font size as the surrounding normal text, or one size smaller if there is difficulty fitting it in.  It should not go more than one size smaller, though, to ensure readability.  When captioning tables, the caption should appear above the item.

References and Citation Styles

DARIAH-Campus itself uses the DataCite metadata model for citing training resources on the platform.  This offers a simple and transparent method for citing different types of research outputs.

However, there is currently not a citation language style (.cls) file available for the DataCite citation style that can be used with citation management software. This means that, while DARIAH-Campus wishes to support and indeed encourages the accurate citation of data, ideally with DataCite,  we recommend the use of the American Psychology Association (APA 7th edition Grammar Style) style within the resource itself. The citation format for APA 7th Edition is similar to that used by DataCite. An example of this is as follows:

Filiposka, S., Green, D., Mishev, A., Kjorveziroski, V., Corleto, A., Napolitano, E., Paolini, G., Di Giorgio, S., Janik, J., Schirru, L., Gingold, A., Hadrossek, C., Souyioultzoglou, I., Leister, C., Pavone, G., Sharma, S., Mendez Rodriguez, E. M., & Lazzeri, E. (2023). D2.2 Methodology for FAIR-by-Design Training Materials (1.4). Zenodo. Report.  https://doi.org/10.5281/zenodo.8305540

Use of URLs and Other Hyperlinks Within the Text

If referring to another website or webpage within the content of a resource, it is best to include that website as a hyperlink within the text, and then reference it below in a ‘Further Reading’ section.

Persistent identifiers are preferred wherever possible, to ensure that information is retrievable on a long-term basis.

Individual Resource Types

There are four main resource types on DARIAH-Campus: Hosted Resources, Captured Events, Pathfinders, and External Resources.  Furthermore, any combination of these resources can be grouped together thematically to produce a ‘Curriculum’.  The general house style discussed above is applicable for all these resource types, but the structure for each can differ slightly.  This section looks at each resource type in turn and specifies the requirements and overall structure for each.

Examples of each of the different resource types have also been created in draft form.

• Example Hosted Resource draft 
• Example Captured Event Resource draft
• Example Pathfinder Resource
• Example External Resource
• Example Curriculum

Hosted Resources

Hosted resources refer to training or learning resources that are published directly on DARIAH-Campus, and follow a traditional lesson-like structure, or offer an audio-visual component that hasn’t been published elsewhere.  The hosted resource option offers options in formatting and content, including quiz options, a table of contents (recommended for all hosted resources), and call-out notices to highlight important information.

The typical structure of a hosted resource on DARIAH-Campus is as follows:

• Brief Introduction to the course;
• Preparatory Notes, e.g. information about any sample data, tools or software that must be downloaded or accessed before beginning the resource;
• Prerequisites;
• Learning Outcomes (this should be ‘Heading 2’);
• Section 1 Heading (use ‘Heading 2);
  • Section 1 Introduction;
  • Sub-heading 1…. (structure continues as desired).
• Conclusion Section (use ‘Heading 2’) with remarks to summarise what has been learned and offer possible areas for further exploration.

You can find the Example Hosted Resource in the DARIAH-Campus GitHub Repository.

Captured Events

The Captured Events feature in DARIAH-Campus enables the gathering of typically ephemeral materials associated with training events, and draws them together to allow self-directed learners to follow along with the lectures and exercises presented.  Furthermore, it is possible to cite the event, including specific presentations from that event.

The captured event format allows for the following format-types:

• Lecture and Presentation Videos (via YouTube, Nakala, or Vimeo);
• Event Photos (via Flickr);
• Speaker Biographies;
• Preparatory Notes;
• Organisational Team Information (for citation purposes);
• Acknowledgments of Funding;
• Presentation Slides (via an external trusted repository, e.g. HAL or Zenodo);
• Handouts (via an external trusted repository, e.g. HAL or Zenodo);
• Exercises.

The structure for Captured Events can vary according to each event, however the basic required information is as follows:

• Event Title;
• Event Subtitle;
• Event Date;
• Authors / Organisers (all authors or organisers are required to have a profile photo);
• Brief Abstract to describe the event;
• Learning Outcomes;
• Preparatory Notes;
• Session Titles;
• Session Descriptions;
• Individual Session Content:
  • Video (via YouTube, Nakala or Vimeo);
  • Presentation Slides (via e.g. Zenodo);
  • Handouts (via e.g. Zenodo);
• Session Speaker Biographies;
• Session Speaker Profile Photos.

The Example Captured Event Resource draft can be found on the DARIAH-Campus GitHub Repository.

Pathfinder

Pathfinders take a hybrid approach in content compared with other resource-types, sitting somewhere between a blog-post and a literature review.  Pathfinder resources typically focus on a specific topic, and discuss the different facets of that topic with reference to resources either catalogued on DARIAH-Campus, or available elsewhere.  They can look specifically at the training and learning resources available for a specific subject, or they can also bring in references and links to other materials such as policy documents, podcasts, video essays or news articles that further the outline of the topic under discussion. 

The typical structure for a Pathfinder resource is:

• Brief Introduction to the topic under discussion
• Brief Introduction to the Pathfinder;
• Learning Outcomes (this should be ‘Heading 2’);
• Section 1 Heading (use ‘Heading 2);
  • Section 1 Introduction;
  • Sub-heading 1…. (structure continues as desired).

• Conclusion Section (use ‘Heading 2’) with remarks to summarise what has been learned and offer possible areas for further exploration.

The Example Pathfinder Resource draft can be found on the DARIAH-Campus GitHub Repository.

External Resources

External resources refer to the resources that are not published directly on DARIAH-Campus. They are contextualised and catalogued in DARIAH-Campus and the respective resource page guides the user to the original resource.

The typical structure of an external resource on DARIAH-Campus is as follows:

• Brief Introduction to the course;
  • Description of course content
  • Issues covered
  • Formats that the users encounter (video, text based, multiple modules)
• Learning Outcomes (this should be ‘Heading 2’);
• Link to the resource (persistent identifiers are preferred)

The introduction to the course should be a short paragraph, not a bullet point list. On the other hand, learning outcomes should be presented as a bullet point list, completing the sentence “at the end of this course, learners/you will be able to:”. You might add a (decorative) image and prerequisites that are relevant prior to accessing the resource.

Please note that the external link should take the user directly to the respective resource and not to a catalogue, general website or aggregator.

The Example External Resource draft can be found on the DARIAH-Campus GitHub Repository.

Curricula

For the most part, the structure of curricula is already pre-determined by the metadata.  However, once you have completed all the metadata, including adding the resources that you want to include, you are also required to give a brief description in which you can give an introduction to the overall theme and topic of the curriculum, the structure of the curriculum, any prerequisites that learners may need to engage with the resources in the curriculum, and acknowledgements for any funders and other relevant stakeholders who directly enabled the curriculum to be developed.

The Example Curriculum draft can be found on the DARIAH-Campus GitHub Repository.

Accessibility

Accessibility should be a key consideration in the production of training materials so that all users, regardless of their ability, can fully engage with and benefit from the resources provided. By incorporating accessibility principles from the outset, training materials are more likely to be used by people with diverse needs, including those with visual, auditory, cognitive, or motor impairments. This approach not only broadens the reach of the training materials but also aligns with inclusive education practices, promoting equal access to knowledge and learning opportunities. DARIAH-Campus therefore emphasises the importance of designing content that is compatible with assistive technologies, structured in a clear and user-friendly way, and available in formats which accommodate different learning preferences.

Tips for Writing Web Content

Section Titles, Headings, Subheadings and Paragraph

For each section, provide a short title that describes the page content and distinguishes it from other sections. Put the unique and most relevant information first. For sections that are part of a multi-step process, include the current step in the section title.

Use short headings to group related paragraphs and clearly describe the sections. Good headings provide an outline of the content.

Use whitespace and proximity to make relationships between content more apparent. Style headings to group content, reduce clutter, and make it easier to scan and understand.

The DARIAH-Campus CMS already follows recommendations on an easily legible style that uses a Sans Serif font, size of 14 points for normal text (paragraph) and a line spacing (leading) is at least space-and-a-half within paragraphs, and paragraph spacing is at least 1.5 times larger than the line spacing. Text is not justified (aligned to both the left and the right margins).

Customisable Text (Controlled by the Code)

Some users need to be able to change the way text is displayed so that they can read the text. This includes changing the size, spacing, font, colour, and other text properties. When users change these properties, no information or functionality should be lost, and the text should re-flow so users don’t have to scroll horizontally to read sentences. Text customisation is more than the zoom functionality, which only changes the text size. For this to work, content must be properly designed and coded so that it can adapt to different customisation settings. The DARIAH-Campus CMS ensures that users can change the way the resource is displayed. Please use predefined headers etc when creating your resource in the CMS. Should you require specific customised components, the editorial team is happy to help.

Meaningful Link Text

Write link text so that it describes the content of the link target. Avoid using ambiguous link text, such as ‘click here’ or ‘read more’. Indicate relevant information about the link target, such as document type and size, for example, ‘Proposal Documents (RTF, 20MB)’.

Text alternatives for Non-Text Content

For audio-only content, such as a podcast, provide a transcript. For audio and visual content, such as training videos, also provide captions. The audio and captions should be in the same language. Include in the transcripts and captions the spoken information and sounds that are important for understanding the content, for example, ‘door creaks’. For video transcripts, also include a description of the important visual content, for example ‘John leaves the room’.

Alternative Text (Alt Text) for Images

Ensure that alternative text (alt text) for images is added to all informational and functional images.

All images should include ‘alt text’ to assist screen readers. Alt text describes the image in a visual way. This is particularly important where the image directly relates to the information given in the main body text.  An example could be in the case of social history studies where a group of people is shown, and the author wants to discuss the diversity or lack thereof within a certain part of society.  It would therefore be important to describe the group of people according to relevant demographics or other social variables, such as gender, ethnic background, ability. Furthermore, it may be useful to describe the various positionings of people, e.g. who is standing and who is sitting; who is standing at the front of the image compared with those at the back.

When the image is purely for decoration, and doesn’t hold any informational or contextual value to the body text, alt text is not necessary. An example here might be if there is a border put around the text, or it is a background image.  Where this is the case, it is useful to indicate as much in the figure widget’s assistive text field by leaving the field blank.

For more notes and information on when alt text is required, you can visit the W3 Alt Text Decision Tree here: https://www.w3.org/WAI/tutorials/images/decision-tree/.  For tips on writing useful alt text, we recommend taking a look at the AxessLab notes on writing alt text here: https://axesslab.com/alt-texts/

Provide Clear Instructions

Ensure that instructions, guidance, and error messages are clear, easy to understand, and avoid unnecessarily technical language. Describe input requirements, such as date formats. 

Keep Content Clear and Concise

Use simple language and formatting, as appropriate for the context:

• Write in short, clear sentences and paragraphs.
• Avoid using unnecessarily complex words and phrases.
• Expand acronyms on first use. For example, Web Content Accessibility Guidelines (WCAG).
• Consider providing a glossary for terms readers may not know.
• Use list formatting as appropriate.
• Consider using images, illustrations, video, audio, and symbols to help clarify meaning.

Tips for Designing and Images

Contrast Between Foreground and Background

Foreground text needs to have sufficient contrast with background colours. This includes text on images, background gradients, buttons, and other elements. This does not apply for logos, or incidental text, such as text that happens to be in a photograph.  A useful tool for contrast check: https://snook.ca//technical/colour_contrast/colour.html 

Background images can be those that are designed to sit either behind text, or another image. It is important, therefore, to ensure that the background image does not impede the readability or visibility of the image in front of it. For this reason, any images that are set to have text added over the top must be as low contrast as possible. This enables the text to stand out.  This is particularly important on resources such as the captured event, where a background image sits in a frame with text overlaid on top.

Be mindful of red/green and blue/yellow colour blindness.  This is where an individual is unable to distinguish between one of these two pairs of colours: that is a person with red/green colour blindness is unable to distinguish between red and green, likewise for a person with blue/yellow colour blindness trying to distinguish between blue and yellow.  Be sure not to sit these colours on top of or next to one another if there is a need to distinguish between them, e.g. red text on a green background or a graph with yellow and blue datasets. 

Don’t use colour alone to convey information.

While colour can be useful to convey information, it should not be the only way information is conveyed. When using colour to differentiate elements, also provide additional identification that does not rely on colour perception. For example, use an asterisk in addition to colour to indicate required form fields, and use labels to distinguish areas on graphs.

Interactive Elements and Identifiable Feedback

In DARIAH-Campus, interactive elements such as links and buttons have distinct styles to make them easy to identify. Please use the elements provided in your resource.  Also, when you use the predesigned widget and style elements provided in DARIAH-Campus, users will receive immediate feedback on items such as feedback on quiz question answers.  You should ensure that your feedback is unambiguous, concise and easy to understand (e.g. ‘correct!’, or ‘that’s not right, try again!’.

Remember Different Viewport Sizes

Consider how page information is presented in different sized viewports, such as mobile phones or zoomed browser windows.  By default, the DARIAH-Campus website is responsive, i.e. the layout and design react accordingly to different devices and scale content.

Include Image and Media Alternatives

Provide a place in your resource for alternatives for images and media. For example, you might need:

• Visible links to transcripts of audio
• Visible links to audio described versions of videos
• Text along with icons and graphical buttons
• Captions and descriptions for tables or complex graphs

Text alternatives convey the purpose of an image or function to provide an equivalent user experience. For instance, if you are creating a tutorial for a tool, and need to explain how to use a specific function to search, an appropriate text alternative for a search button would be “search” rather than “magnifying lens”.   

Other General Tips about Designing

• Images of text are resizable, replaced with actual text, or avoided where possible
• Users can pause, stop, or adjust the volume of audio that is played on a website
• Background audio is low or can be turned off, to avoid interference or distraction
• The Mississippi State University National Research and Training Center on Blindness and Low Vision offers online recommendations to improve accessibility for users with blindness or low vision.  

Formatting Self-Assessment Tools i.e. Quizzes

DARIAH-Campus has a built-in tool for self-assessment, offering a quiz format that allows for responses to a multiple choice question.  When creating quizzes for people who are blind or have low vision, be aware that the assistive technology software, the version of that software, the specific web browser, and the version of that web browser may all play a part in the participant’s survey experience. For example, there are several commonly used screen readers (e.g. JAWS, NVDA, VoiceOver).  Each screen reader interacts differently with web content which can result in a different quiz experience. Survey participants who use older versions of screen readers may experience difficulties with online surveys that people with newer versions do not experience.

General Recommendations

• Make use of the heading options in DARIAH-Campus. These are helpful for screen reader users.

• Question numbers are recommended to assist with navigation.

• If you allow a limited range of responses to a question (e.g. a whole number between 0 and 50), clearly indicate that in the question.

• If questions allow multiple answers, adding text like ‘Select all that apply’ as part of the question is helpful.

• If responses are required for certain questions, indicate that in the question.

• Add alt text to any images used, unless they are decorative or redundant.

• Avoid using video if possible.

• Pilot test your quiz with people who use the assistive technology(ies) of your target group. Even if you follow all accessibility recommendations, pilot testing is needed to uncover any accessibility or usability problems with your survey.  Do this in an ethical way, ensuring that their time for testing is compensated in an appropriate manner.

   

Know Your Question Type

The conventional quiz questions, which typically include radio buttons or select boxes, are relatively straightforward to design with accessibility in mind. However, more sophisticated interactive questions present a greater challenge. Utilising the following six question types (where available) for accessible surveys is a recommended approach: 

• Drop-down menus, 
• Single select, 
• Multiple select, 
• Grids, 
• Numeric entry boxes, and 
• Text boxes. 

These options are not only simple and efficient but also familiar to most respondents, making them an effective choice for collecting data.

Final Remarks

This Style Guide was initially developed as part of the ATRIUM project (specifically in ATRIUM Deliverable 7.2), and has been modified to fit the needs of the broader DARIAH-Campus audience.  Every attempt has been made to ensure accuracy and relevance for the DARIAH-Campus contributor audience.  We welcome feedback on any aspects of this Style Guide.  You can contact any member of the Editorial Team to discuss this further.

DARIAH-Campus is grateful in particular to the team at PRISMA, a partner in the ATRIUM project who provided clear guidelines on Accessibility as part of the ATRIUM Deliverable 7.2.  We have made some modifications in this version to better reflect the features available within the DARIAH-Campus Content Management System.  Again, every effort has been made to ensure accuracy but we welcome feedback in this regard.

References

Tasovac, T., & Garnett, V. (2024). The Guidelines for Producing the ATRIUM Curriculum. Zenodo. https://doi.org/10.5281/zenodo.13867113