About these guidelines ☝
We welcome contributions from our colleagues around the university group to the Teaching Knowledge Base. In order to keep our content high-quality, consistent, practical and actionable, we will only accept submissions to the knowledge base in accordance with these guidelines.
When you’re ready to publish, use the Article Submission Checklist to make sure your content is in line with other articles in the Teaching Knowledge Base.
To be considered for the knowledge base, an article must meet the following critera in addition to meeting the requirements of the rest of the submission guidelines:
- Practical and action based – not theoretical
- Has an obvious outcome in mind for the reader having read it such as “Readers will be able to…” and not “Readers will know…” or “Readers will understand…”
- No more than 2000 words in length
- Not self-promotional in nature
- Does not replicate guidance which already exists on the knowledge base where an update would be more appropriate
Tone of voice
You’re encouraged to write in a friendly, conversational manner throughout your article. The goal is to have an accessible resource where every educator feels welcome and happy to explore the knowledge base.
Here are some tips for setting the right tone:
- Address the reader directly when appropriate – “You can find out more by…”
- Use contractions where appropriate – “Shouldn’t” instead of “Should not”
- Express empathy when explaining something which might feel complicated or tedious to the reader
- Your bio will appear with your article, so feel free to write in the first person if it makes sense to do so
Writing for the web
The knowledge base is an online resource, so it’s important for contributors to keep in mind some strategies for creating content suitable for the web.
Make it brief
Staff coming to the knowledge hub are looking for tips and guides to improve their practice. For many of them, teaching is only one facet of their role within the university, and they’re often very time-poor. Therefore, you should aim to write content which is as short as possible while still delivering something of value.
Respect your readers’ time. You can always link to further resources and reading to give them the option of going deeper if they have the time to do so.
Make it scannable
People read differently on the web; online audiences rarely read articles and posts from top to bottom. We tend to read titles, scan headings, start with conclusions and only read through information if it looks relevant to us.
You can greatly improve your reader’s experience by allowing for this scanning behavior:
- Use different level headings such as H2, H3, H4 to organize your content – this is how the table of contents will be generated on the knowledge base (do not use H1)
- Avoid long paragraphs (3 to 4 sentences is plenty and adding variety in paragraph length helps to keep interest – even single word paragraphs are acceptable)
- Avoid long sentences (The UK Government Digital Service uses a 25 word limit for sentences written for the general public in their content guide)
- Use lists, block quotes, callouts, columns, images, diagrams, video and other tools to break up sections of content longer than 300 words or so
Make it practical
You may have some great insights and arguments for ongoing pedagogical debates, but for most of our readers, they just want to know how to teach well. Writing for the web means understanding your user may be in a rush, on their smartphone or flipping between articles for tips.
Most of our staff will thank you for being light on theory and heavy on application.
This guide will be a resource for thousands of staff members coming from a wide variety of backgrounds. Writing in a way which is accessible to everyone improves understanding for all users.
Use plain English
Plain English expresses information clearly and simply. Even higher literacy learners prefer plain English because it helps them to process information faster.
- Picture your audience and write as though you were talking face to face.
- Do not use long or complex words where short, simple ones will do.
- Remove unnecessary words.
- Avoid jargon and explain specialist terms at the first use.
- Introduce and spell out acronyms and abbreviations at the first use.
There are some formatting tools which should be used in moderation as they introduce increased complexity in comprehension for some readers. These include:
- Writing in ALL CAPS
- Center-aligned text
Write for assistive technologies
Staff accessing your content with a screenreader or other assistive technologies will have a much smoother experience if you take steps to ensure that your articles make semantic sense. This means doing things to support semantic meaning such as
- Organizing content into headings and subheadings
- Not skipping heading levels (like an H2 to an H4)
- Adding meaningful descriptions in the ALT text when adding images to the site
- Avoid putting key information into images without accompanying text or captions
To get more insights into making your content accessible, look at the Writing for Web Accessibility guide from W3.
Access to tools
When referring to digital tools, websites, apps and services in your content, you must be aware of the level of access staff will have to what you’re recommending. Staff will be able to access anything which is either a Core or Supported tool in the Teaching and Learning Ecosystem Document.
You may also refer to tools outside those categories if they are freely available, but you must encourage staff to follow the appropriate guidelines and talk to their Associate Head (Student Experience) when adopting the tool using the disclaimer below.
Media is a great way to make your content more engaging and to demonstrate tips and techniques which are harder to express in writing. It’s also a great way to break up your content to make it more scannable and easier to understand.
The knowledge base editor has options for embedding content such as images, galleries, videos, social media posts and more.
Do not upload content to the knowledge base that you do not have permission to publish, and always include the appropriate attribution and licence information for openly licensed content.
You can refer to the Creative Commons page on the types of open licences to learn more.
N.b. For the purposes of the knowledge base, content must not be taken or adapted from sources which stipulate “Non-commercial” in their license.
Follow the guidelines above for keeping all media accessible such as including key information in images in an accompanying text format or providing captions or video transcripts where possible.
Whether you’re linking to content from another source or to something that already exists in another article on the knowledge base, make sure your links text is specific and meaningful. This improves accessibility and makes it more clear to users what to expect when following your links.
If you’re aware of documentation on the knowledge base which is relevant to something you’re writing, you should try to link to it where possible and appropriate.
In the editor, you can check to see if something is available to link to by highlighting your text, clicking the link icon and typing in some keywords to see if they match articles already on the database.
External links are a great tool for keeping your content on page more concise as well as making your contributions more valuable. Only link to external resources and sources of information that you trust.
You’re allowed to link to content you or your department has produced elsewhere which is relevant to the topic of your article, but keep these links balanced with other resources online. We ask all contributors to avoid unwarranted self-promotion on the knowledge base.
Updating your content
As a contributor to the knowledge base, you’ll have the ability to log back in and change or update your content when you feel it’s appropriate. While there is not yet a formal system in place to review this content, readers will have the opportunity to provide feedback on any article in the knowledge base.
Your content is subject to change by other editors to keep the information as relevant, up-to-date and understandable as possible.