View source for DSNFPS-RSDFPF/Contributing Articles

= Before You Start =
Writing an article requires careful consideration of multiple factors to ensure that your readers will find it interesting enough to read it all the way through.

Before you write anything, ask yourself these questions to help you focus your message:
# For whom am I writing?
#* The network is for anyone working as, with or supervising a data scientist. There are executives, HR, training, and other communities who are trying to support the use of data science in the public service without being data scientists themselves.
#* Write to the target audience. There will often be overlap between multiple groups in the target audience, but there is no need to target all subscribers with every article.
# What is the message I want to convey?
#* What is the ‘take home’ message?
#* Make your point as early as possible, then reinforce it and expand throughout the article.
# How would I summarise the article?
#* The newsletter is only going to have a short description to be able to draw people towards your article.
#* If you cannot summarise the post then it may need indicate a need to reduce the scope or focus the ideas.
# Do readers need any special knowledge?
#* Requiring special knowledge is fine, but it needs to be clear to readers if they are going to understand the topic.
#* Rather than explaining some of the more basic concepts, link to materials that readers can use to get up to speed.
# What is this adding to the conversation?
#* The [https://www.tbs-sct.gc.ca/pol/doc-eng.aspx?id=25049 Values and Ethics Code for the Public Sector] plays a role in the decision to publish an article. If the article is repeating something that exists elsewhere, it is potentially a better use of time and money to highlight the external source rather than recreate an article.

== Article Types ==
Articles fall into different categories depending on their intent. While there is overlap between the different types of articles, it is important to be consistent in your approach and wording to provide a consistent experience.

For our purposes, the [https://documentation.divio.com/ different types of articles] are:
* Tutorial (learning oriented)
* How-to guide (problem oriented)
* Explanations (understanding oriented)
* Reference (information oriented)
Tutorials take a lot of effort to maintain, and therefore do not lend themself to the type of material the network is trying to produce for the blog.

Articles may be trying to explain a concept or series of steps. Ensure that your approach to the concept falls into a single article type throughout the text, and does not confuse the reader as to your intent. Mixing different types of articles makes it harder for the reader to understand your intent, as it is unclear if you are trying to educate them or asking them to follow along in a series of steps.

= Get to Writing =
With the beginning questions answered you can get to writing. There are a few things to keep in mind while writing though.

== Structure ==
It is important that your article have a beginning, middle, and end. Your article should have a story arc that allows the reader to put the article into context, follow you through the topic, and come to some sort of resolution.

=== Introduction ===
The first couple of paragraphs are what will entice the reader to keep reading. This needs to convey the context of the article and how it fits into their existing compendium of knowledge. Make sure you communicate to the reader what value they will derive from reading the rest of the article.

=== Middle ===
This is the main content of the article. You’ve explained what users can expect from the article, and now you are giving it to them. Depending on the topic and objective, the middle of the article may be short or long. Ensure to leave clear indications to help the reader stay oriented as you move through the topic. Headings often help to do this.

=== Conclusion ===
The article needs to have a clean end to it. You need to summarize your topic, restate the takeaways, and maybe have a call to action depending on the objective of the article.

== Important Elements ==
There are some accompanying elements to articles that need to be thought of as well.
* Abstract: Every article needs an abstract that will be displayed to allow readers who land on the front page of the DSN to get a general sense of the topic. These should aim to be about 40-50 words long.
* Accessibility: All images need to be accompanied by descriptive text for assistive devices to use. Also, a description should accompany the image to allow the reader to understand it. All images should be WCAG 2.0 AAA compliant. You can use [https://webaim.org/resources/contrastchecker/ this tool] to test images for minimum contrast levels.

= Other Resources =
The government provides other good resources to help you in writing articles for general audiences. The articles published in the blog will generally follow the guidelines for other GC spaces as well.
* [https://www.canada.ca/en/treasury-board-secretariat/services/government-communications/canada-content-style-guide.html Canada.ca content style guide]
** [https://www.canada.ca/en/treasury-board-secretariat/services/government-communications/canada-content-style-guide.html#toc5 Writing principles for web content]
** [https://www.canada.ca/en/treasury-board-secretariat/services/government-communications/canada-content-style-guide.html#toc6 Plain language]

== Helpful Hints ==
Some items to keep in mind as you write:
# Is all the terminology explained?
#* Expand acronyms and abbreviations.
#* Define any terms that need it. This isn’t a journal article, so things like glossaries are not available. Terms need to be defined as they are used.
# Write as a peer of your readers.
#* Use language like “we can see that”, rather than “you will find that”.
# Think about visuals.
#* Readers will not like to have a long screen of text to read through.
#* Visuals can consist of graphics, charts, or anything that helps make your point.
# Try to avoid overly long sentences and paragraphs.
#* Readers will find it easier if content is broken into ingestible chunks.

= Example Articles =
Here are some examples of the types of writing produced in similar publications, and you can always check the [https://www.statcan.gc.ca/eng/data-science/network existing articles].

== Quick Overviews ==
Articles that are trying to give the reader a quick introduction to a topic are generally short and describe the topic at a high level to reach the largest audience possible.

=== Examples ===
* [https://www.ordnancesurvey.co.uk/business-government/products/case-studies/stroke-nhs Ordnance Survey data helps hospital open in Sumerset]
* [https://datasciencecampus.ons.gov.uk/extracting-visualising-and-identifying-emerging-important-terminology-from-patent-collections/ Extracting, visualising and identifying emerging important terminology from patent collections]
* [https://www.capitalone.com/tech/open-source/open-source-global-attribution-mapping-for-neural-networks/ Global Attribution Mapping]

== Full Length Articles ==
Some topics warrant a long article to allow for a fuller explanation than an overview can facilitate. The article is still presented at a relatively high level, and is intended for a broad audience, but needs a lot of room to properly explain the topic.

=== Examples ===
* [https://datasciencecampus.ons.gov.uk/mapping-beaches-with-the-data-science-accelerator-programme/ Mapping beaches with the data science accelerator programme]
* [https://datasciencecampus.ons.gov.uk/data-science-for-sustainable-development/ Data science for public good]
* [https://datasciencecampus.ons.gov.uk/inspiring-the-next-generation-of-girls-in-data-science/ Inspiring the next generation of girls in data science]

== Short Article with Long Follow-up ==
Some articles are initial introductions to a question or concept that is then followed up with an in depth exploration of the topic. These are presented as two distinct articles – a first one that presents a question or topic at a high level, and a second that explores or explains the topic in depth.

=== Examples ===
* Predicting energy efficiency using machine learning.  Short introduction: [https://datasciencecampus.ons.gov.uk/can-machine-learning-be-used-to-predict-energy-performance-scores/ Can machine learning be used to predict energy performance scores?]  Long follow up: [https://datasciencecampus.ons.gov.uk/projects/using-machine-learning-to-predict-energy-efficiency/ Using machine learning to predict energy efficiency]
[[Category:Data Science]]