Newsletter’s Style Guide¶
In the previous subchapter, we described the process of drafting, reviewing and publishing The Turing Way’s monthly newsletters.
In this document, we have listed some guidelines to maintain consistency across all the newsletters.
File format: Draft the newsletter in Markdown
Filename: Create a filename with the “newsletter_serial_MonthYYYY.md ” format, where “serial” should be replaced by the serial number (in numerical) of the newsletter, the month should be replaced by the short name of the month and YYYY with the year in numerical.
File location on The Turing Way GitHub: The newsletters are currently stored in the path “the-turing-way/communications/newsletters/”.
This location also consists of a “README.md” file that has a table for all the published newsletters that are updated after each release.
This location has a folder called “images” that centrally holds all the images and linked to the corresponding newsletters.
Dates: “DD Month YYYY” format
use it consistently in the entire document
To reflect a range, use “from DD to DD Month YYYY” format.
Even if the sentences have reference to a day in “yesterday”, “today” or “tomorrow”, provide the exact date inside parenthesis so that it still makes sense if someone reads a newsletter in the future.
Time: Use time in Greenwich Mean Time (GMT) or British Summer Time (BST), followed by a link from arewemeetingyet.com to check the time in relative time zones
Links: Use the Markdown formatting for link like this,
[text that needs to be linked](full HTTP link)Provide links wherever useful, for example, HackMD for Collaboration Café, GitHub issue, registration pages and see details.
Create link for email ids using this Markdown syntax -
[real-email-id](mailto:real-email-id)
Quoting others: Use smaller than (>) symbol followed by a space before the quoted sentence. For example:
> This is my legendary quote.will appear as:This is my legendary quote.
Header and styling: The newsletter title is the top header.
Different sections as suggested in the newsletters are second-level headers and the sub-sections are third-level headers.
Use bold letters, italics, hyperlinked texts and quotations wherever applicable
The project name, The Turing Way, should be italicised.
Use line breaks for each line consistent with The Turing Way writing format.
Leave at least one line space after each section and subsection.
Language and tone: Keep the overall language simple and jargon-free, see The Turing Way style guide for reference.
The tone should be welcoming, friendly and preferably informal. This can be personal to the author’s writing style.
Ask more than one person to review your draft to make sure that its content is easy to understand and written clearly.
If using content from a language or culture different from your own, ask people with that language or culture to review your draft to make sure that contents are not misrepresented.
Use of emojis: It is encouraged to use emoji (show your personality) 😇, but keep it simple, neutral and positive.
Be aware that that ambiguous emojis can be misinterpreted by different readers.
When in doubt, ask someone to review your draft.
Use of images: Only use relevant images linked to the news item in the newsletter.
Make sure that the images are available under CC-BY license or approved to be reused by the owners.
Avoid using memes, images with political or sexual innuendo, or anything that is not directly related to the community.
When drafting the newsletter in a HackMD, drag-n-drop an image into the editor or copy-paste an image to automatically upload the image to Imgur.
When drafting the newsletter on the GitHub, upload the images in the folder “the-turing-way/communications/newsletters/”.
File naming convention for the images is “short-name-monthYYYY.png”, where the short-name should be replaced with the identifiable short name of the image, the month should be replaced by the short name of the month and YYYY should be replaced by the year.
File extension can be ‘.jpg’, ‘.png’ or other with compatible image file type.
Use Markdown syntax to link the images in the newsletter:
.As suggested in The Turing Way style guide, create an alt text for the image:
Below the image, write a short descriptive title for the image followed by an empty line. Link title to the source such as a tweet or related event.
When using multiple images as panels in one collective image, number each image clearly (this can be done in any photo or text editor) and provide a numbered title for each image. See an example here.