Author Guidance & Style Guide

Structuring the DS Topic Guide

Each DS Topic Guide follows a distinct structure, beginning with a Header Section (Front Matter) composing of the guide Title, Authors, Affiliations, Published date, Last modified info, and Abstract followed by five key content blocks detailed below. Please have a look at the Getting Started in DS as an example of how these pieces all fit together into one complete DS Topic Guide.

Front Matter

This markdown template shows an example of what information is required for the header, and how each section should be formatted and can be used as the basis for starting a new guide. Note: The project team will ensure each_DS Topic Guide_ is given an individual DOI through Zenodo once published.

I: Introduction to the topic

This section should provide a concise overview of the topic, written in a relaxed and natural way. It does not need to contain the world’s knowledge, just enough high-level knowledge to get the key concepts across. It should be pitched at a beginner/foundational level.

Linking can be used liberally for terminology and concepts throughout if explaining a particular term is more complex than space allows. Please see the Style Guidelines below for more writing tips!

II: Relevance to the Library Sector

This section provides a clear explanation of the topics’ specific relevance to the work of libraries.

It should contain:

• A short paragraph or two setting the scene as to why the topic is relevant to the work of libraries. Here you might also like to present opportunities and, if relevant, potential challenges for libraries around the topic as well.
• Up to 3 examples of real world (or potential) applications/case studies/projects, briefly explained, with links to further information if available. Note that it is not necessary to write up or create a new case study or use case yourself here, though you’re more than welcome to! If there are quite a few other examples to include, links to these can be added at the end of the section (Example: “For further case studies, visit….”).

III: Hands-on activity and other self-guided tutorial(s)

The objective of this section is to enable learners to familiarise themselves with the basics of the topic through active practice via self-paced tutorials and hand-on activities. Authors are not expected to create new activities or tutorials in this section, but rather to provide selected links to existing hands on tutorials which are known by them to have proven value and can be personally recommended for library professionals in particular.

The tutorials recommended should be free, online and suitable for independent study, and ideally, focussed on the library professional perspective where possible. Authors may wish to link to practical exercises or quizzes, specific online lessons that may exist in other online platforms, Juptyer Notebooks and GLAM workbench materials that provide detailed explanations of the steps learners can follow.

Suggested tutorials should be open access, not behind a paywall.

For the sake of consistency across the various topic guides, it is helpful if tutorial references are structured as follows:

• The title/name of the activity/tutorial, the URL (added as a hyperlink) and/or provide a DOI if there is one)
• A brief, personal explanation below it (no more than 200 words) as to why the author recommends this particular tutorial, and, optionally, an indication of topics covered and the level of complexity.

IV: Recommended Reading & Viewing

The section on recommended reading and viewing contains references to more passive learning resources such as:

• Open access articles discussing the topic at a general level, or containing contextual information.
• Video recordings of lectures about the topic, which do not demand practical activities from the viewer (these can be embedded here)
• Podcasts about the topic

When including citations please make sure to provide the DOI with your text if possible so that the project team can compile a dedicated Zotero Library.

We discourage adding links and recommendations to materials that are behind paywalls, or otherwise inaccessible easily online/remotely. We recommend use of a VPN for verifying this as sometimes library institution set-ups can make it harder to realise that articles are not free!. If, however, there is an obvious seminal reference work, provide a full reference for it, explain that it is paywalled content or not digitised, and point readers to Worldcat if possible so they can find it in their library.

V: Finding Communities of Practice

This section provides guidance to library professionals on where they can find networks or additional support from like-minded colleagues for taking their learning journey further. It should include:

• Where to find (local/national/international) Communities of Practice or other relevant networks and organisations who can help with furthering their understanding of the topic.
• If relevant you might also point to specific summer schools, conferences and other learning events that may further enhance networking and thus learning around a particular topic.

Style Guidelines

Think: Natural, Casual, Accessible, and Internationally Inclusive Content

Imagine that a colleague has come to you casually asking about the topic over tea. How might you go about explaining it to them in your own words? During the course of that casual conversation what key things would you leave in and what might you leave out in the interest of getting them to a basic understanding of a complex topic quickly?

Though reviewed and edited by peers, DS Topics Guides are not meant to be written in the style of scholarly papers or journal articles, and instead their style is more in keeping with LibGuides, blogs and personal articles. As such, they should be written in a natural and relaxed manner, but to ensure consistency and inclusivity across our content, please consider these general guidelines:

• Clarity and Simplicity: Write in a clear and straightforward manner, using simple language that is easy to understand for learners of all backgrounds and proficiency levels.
• Linking to Technical Terms: When introducing technical terms or concepts that may be unfamiliar to some learners, provide hyperlinks to additional resources or definitions where they can learn more. This helps to enhance understanding and allows learners to explore topics in more depth at their own pace. Ensure that the linked resources are reliable and authoritative to provide accurate information to the learners.
• Avoid Colloquialisms and Regionalisms: While it’s essential to maintain a casual and natural tone, please refrain from using colloquial expressions or regionalisms that may not be universally understood by our diverse audience.
• Cultural Sensitivity: Be mindful of cultural differences and avoid language or examples that may be offensive or insensitive to any group of people. When providing examples or references, strive for universality and inclusivity.
• Gender Neutrality: Use gender-neutral language whenever possible to ensure inclusivity and avoid assumptions about gender roles or identities.
• Global Perspective: Consider the international nature of our audience when crafting examples, scenarios, and references. Aim for content that resonates with learners from various cultural backgrounds and geographical locations.

Checklist for Authors & Reviewers/Editors

The following checklist reflects the key areas Reviewers and Editors will be checking over with each submitted DS Topic Guide. Authors should find this helpful too and consult it before submitting their work for final review.

Front Matter (for Topic Guides only)

• Abstract is clear, concise and reflective of topic
• Author names are linked to a LIBER profile where possible or a personal/business bio page
• Author orcid id’s are included and resolving correctly
• Title follows correct capitalisation (Capitalise the first, last and ‘important’ words)
• Check for references to old “DS Essentials” and replace with “DS Topic Guides”

Content

• Content is clear and complete and follows the Style Guidelines above
• Text reflects the aim of the section (for example, Finding Communities of Practice recommends networks/networking/conferences etc. rather than advanced tutorials/lessons)
• Images on the page are directly illustrative of the point/necessary
• Check for typos
• Check any activities provided work
• Recommended hands-on activities and self-guided tutorials should be Open Access and freely available online
• Recommended Reading & Viewing content (scholarly texts/articles/books/manuals) should be Open Access by default and not behind a paywall. (We recommend use of a VPN for verifying this as sometimes library institution set-ups can make it harder to realise that articles are not free!) If this is not possible and it is a seminal reference work, provide a full reference for it, explain that it is paywalled content, and point readers to Worldcat if possible so they can find it in their library.

Text Formatting Edits

• Written in British English which is the style of the EU
• Check for markdown errors
• Check for references to old “DS Essentials” and replace with “DS Topic Guides”
• “Topic Guides” is always referred to and written in italics as “DS Topic Guides”
• “Digital Scholarship & Data Science Topic Guides for Library Professionals” is always italicised when referenced in text. Note the use of “&” and not “and”
• Headings are correctly formatted. The title of each guide is already in h1# so main section headers such as “Introduction” should be second-level header with h2 tag ##.
• Capitalise the first, last and ‘important’ words of every heading; for example, ‘Snow White and the Seven Dwarves’.
• Replace Latin abbreviation (eg., ex., etc.,) with full text (Accessibility)

Links

• Check all links to ensure there are no broken ones
• Internal links to content within the site (such as reference to other DS Topic Guides) should be relative rather than absolute and use the .qmd extenstion. For example the markdown would look like “See the [IIIF Topic Guide](iiif.qmd).” rather than “See the [IIIF Topic Guide](https://libereurope.github.io/ds-topic-guides/iiif.html).”
• External links should include the “https://”
• We highly discourage linking to articles that are behind paywalled content. However, if it is a seminal reference work, provide a full reference for it, explain that it is paywalled content, and point readers to Worldcat if possible so they can find it in their library.

Images

• Images should be public domain or CC0 as our guides are shared under CC-BY
• Images have alt-tags and captions (Accessibility)
• Images are all saved in the project GitHub folder: https://github.com/libereurope/ds-topic-guides/tree/main/book/images (this will be automated, reviewer can ignore)
• Images are in .jpg or .png or .svg format and ideally less than 1MB (this will be automated, reviewer can ignore)
• Images are no larger than the width of our body text column (width should be less than 949 pixels) (this will be automated, reviewer can ignore)