# The Content Writing & Publication Process at Datopian

# Document Introduction

Datopian has a variety of services and products that are offered to our clients. Marketing these are important for brand building and establishing Datopian as world leaders in data services. It also strengthens our relationship with our clients and helps with our outreach to new potential clients.

This document outlines the content publication process at Datopian across multiple channels. If you encounter an issue that is not covered by this project, open an issue on the Bizdev tracker and tag one of the current reviewers (@annabelvandaalen or @paulwalsh.)

# Content Production Overview

  • Datopian produces different types of content (such as blog posts, case studies, feature updates etc.) and some of these types follow a template.
  • Our written content aids client and potential-client understanding of what we do and the sorts of topics we are engaged in.
  • Content production is a collective responsibility.
  • Datopian has a master spreadsheet that tracks our content pipeline and status.
  • We use American English for all external content.

# The Writing Process

# Overview

This section provides guidance on how to structure written content depending on the type of content being produced. Some content types require a specific template. Please see the guidance below for information on each content type, including structure, audience, tone and content (complete with examples!).

# Checklist

  • Create an issue on the Editorial Board (note: the editorial board should only be used for works in progress so that other Datopians can collaborate with you - any content ideas for future posts should be logged in the master spreadsheet).
  • Draft the article, tweet or Blog (including a list of tags for the article).
  • If any of your content contains terms that you think would make interesting additions to the glossary, add them on GitLab here: https://gitlab.com/datopian/core/datopian.com/-/tree/master/site/glossary.
  • Make sure your content ends with the following paragraph about what we do in italics and with links embedded:

Want to work with Datopian? We are data management experts providing open-source tooling and related services to organisations worldwide. Check our website for more information or contact us.

Here it is in Markdown so you can copy-paste:

_Want to work with Datopian? We are data management experts providing open-source tooling and related services to organisations worldwide. Check our [website](https://www.datopian.com/) for more information or [contact us](https://www.datopian.com/contact/)._
  • Make sure that you add the license at the bottom of the page: © Datopian (CC Attribution-Sharealike (by-sa)).
  • Create the abstract or intro for the article on our social media platforms, such as LinkedIn, Facebook and Twitter.
  • Ensure that links and background information are provided in the issue created for the article.

# Content Types

The content we produce at Datopian is split into 8 content types (with some content types split into subtypes). These are:

  1. Client Interviews
  2. Case Studies
  3. Briefings
    3a. Technical Briefings
    3b. Expert briefings
  4. Updates/Announcements
    4a. Feature and functionality updates/announcements
    4b. Projects going live announcements
  5. ‘About us & culture’ posts
    5a. General articles
    5b. Travelling Datopians photo essay
  6. Hobby-blogger posts
  7. Newsletters
    7a. Bi-annual projects update newsletter
    7b. Feature newsletters
  8. Reviews

# Content Structure & Templates

# Client Interview

Interviews are unstructured to allow the interviewer room to respond spontaneously to points made by the client. However, it is good to keep in mind the aim of your interview and any key pieces of information you need to find out.

Template N/A
Tone When written up, the questions should be phrased informally to reflect the natural flow of a conversation. However, they should not include spoken mannerisms such as ‘um’, ‘yeah’, ‘right’ etc. You should feel free to paraphrase questions to allow for easy reading.
Example https://www.datopian.com/blog/2020/05/12/oced-case-study/

# Case Study

Case studies have their own separate section on the website and should all be structured in the same manner. They aim to show a client’s journey from first encountering a problem and hiring Datopian to our current projects together. They should draw attention to the ways in which Datopian has helped our client through bespoke solutions.

Template Please use the template: https://docs.google.com/document/d/1vLf-fcHc9rhgYcsLP2HfjovPhUUV4Dgh1hs48azx5HI/edit#heading=h.vkr66n97gatf
Tone Case studies are not blogs and articles, but structured pieces of content that are much more formal in tone.
Example https://docs.google.com/document/d/1R4nvc4DDZEhp9ZQFTKMAdm1AfVTUFtaSrGtOzSiEU8w/edit#heading=h.m1gy4aodpy3

# Briefing

Briefings are split into two types: expert and technical. Technical briefings are specific to certain technologies or very technical in character. Expert briefings are more general in scope and tackle wider data themes.

Template N/A
Tone Formal but with room for the writer’s own voice and writing style to shine through.
Audience Both briefings should assume little prior knowledge. This means that writers should make an effort to ensure articles are accessible enough for anyone to understand, while still containing an element of depth to make them interesting for more expert audiences. In a nutshell, this means going into as much detail as possible while also explaining that detail.
3a. Technical Briefings Includes: articles on CKAN, software, programming, file formats, data specifications, DMS.
3b. Expert Briefings Includes: thought-leader posts, opinion pieces, general data posts.

N.b. An article on DMS could potentially be either an expert briefing or a technical briefing. The difference between them is: Technical Briefings focus on specific technologies and technical explanations, eg. might explain how a DMS functions, whereas Expert Briefings are more general in scope, eg. might discuss the benefits of DMS for enterprise.

# Announcement/ update

Announcements are split into two types: feature & functionality updates (templated) and projects going live updates (non-templated). Both types of announcement should include (where possible): demos, screenshots or diagrams; a link to the project; a call to action; a link to the GitHub code. The announcement should begin with a brief summary of the feature/project.

Template Please use the template: https://docs.google.com/document/d/17BHiYhUA7f-K4OIn2Plc-gfdn-69g6NaJXu40VYfqyo/edit#.
Audience Especially in the case of feature & functionality templates, we can assume some prior knowledge. Because these are aimed at clients already using the feature, announcements should go into technical detail about key aspects. However, they should not contain information about the codebase - this can be found through the link to GitHub.
Tone Formal with enthusiastic language, eg. we are proud to be working with/we are excited to announce etc.
4a. Feature & functionality updates Under the ‘why this new feature?’ heading in the template, it is important to frame the feature in terms of why we did it for a certain client with the use cases X, Y and Z. Check with the project manager whether the client can be named - if not, describe the company eg. ‘a fortune 100 pharmaceutical company’.
4b. Projects going live updates If possible, it would be great to include a quote from the client.

# About Us and Our Culture

Datopians are encouraged to write blog posts on any aspect of Datopian culture or methods. These could be casual or philosophical in scope. Posts could range from: discussions on agile project delivery, different approaches to remote working, philosophical musings, or how we approach software development.

Template N/A
Tone Informal and lighthearted.
General article See example: https://www.datopian.com/blog/2020/03/24/tips-on-remote-work/#use-your-video-for-meetings-whenever-possible
Travelling Datopians photo essay Include as many photos as possible and use the caption as a means of explaining your story.

# ‘Hobby-blogger’ posts

‘Hobby-blogger’ posts aim to give Datopians the space to discuss personal projects and views that are loosely linked to Datopian’s work. These could include tech/software builds or responses to data-world developments. Photos are mandatory! 😃

Template N/A
Tone Informal and lighthearted.
Example https://www.datopian.com/blog/2020/01/08/running-a-scraping-platform-at-google-cloud/#the-architecture.

# Newsletter

Datopian produces two types of external newsletter: a bi-annual update on our client projects and more frequent feature newsletters. Feature newsletters mainly consist of interviews with Datopians, clients or industry professionals.

Template In progress.
Tone Formal.
7a. Bi-annual newsletter This must include an opening word from the leadership team (Rufus, Paul, Esteban) and a short overview of all ongoing client projects.
7b. Feature newsletters Feature newsletters could be anything - we are open to suggestions! Generally speaking though, many will take the form of interviews on a certain topic.

# Reviews

Datopian does not currently write any reviews and these are not a priority at present. However, this route is open for exploration at some point in the future.

# The Publication Process

The purpose of the Publication process is to ensure that Datopian’s content production is informative, regularly scheduled and a good representation of the work we do.

# Checklist

  • Ensure published content - including language, links, image accreditation etc. - is accurate.
  • Share with either @annabelvandaalen or @paulwalsh for review.
  • Where the article is based on a client interview or case study, liaise with the client to ensure there is a common understanding around the publication content and that the material to be published has client approval.
  • Publish the content on Datopian’s blog.
  • Update Content Publication Master Spreadsheet.
  • Add new key terms to the glossary.
  • Post-publication client engagement including:
    • Informing the client of the publication.
    • Sending them the links to the various channels that the article has been published on.
    • Thanking them for their input.

# How to post on the blog

# Overview

Posting on the blog requires GitLab and Visual Studio Code. If you haven’t already downloaded Visual Studio Code, you can find it here. Working with this software requires you to do some basic coding, but you by no means need to be a programmer to learn how. Simply follow the steps below! We would recommend looking at how other articles have been coded at each coding step to make sure you understand how to implement the instructions.

  1. Open the repository on GitLab. Click on the blue ‘clone’ button and copy the second URL.
  2. Open Visual Studio Code and go to the Terminal tab at the top → select ‘New Terminal’. The terminal is the part of the software where you write instructions.
  3. In the terminal, type in git clone followed by the copied link, like this: git clone https://gitlab.com/datopian/core/datopian.com.git. Press Enter on your keyboard.
  4. In the explorer tab on the left, find the blog folder and right click on it. Select New Folder. Name the folder using the naming convention yyyy-mm-dd-your-blog-post-title (Example: 2019-03-01-viderum-renaming-to-datopian).
  5. Now right click on the folder you just created. Select New File and name it README.md. This is the file you will use to create your article.
  6. Now you need to upload your thumbnail image to this folder. This is the image that will show up next to your post on the blog homepage. To do this, save the photo to your device and name it (using dashes to separate words instead of spaces) and drag and drop it to the new folder you just created in Visual Studio Code. The photo should now be in your blog post folder alongside the README.md file.
  7. Now you need to upload any other photos for your blog post to Visual Studio Code. Staying in the explorer tab, go to Vuepress → Public → Assets → Image → Blog. Save the images you need to your laptop and drag and drop these into this folder (there should be lots of images already there).
  8. Go back to your README.md file and add the following code to the document (this should stay at the top of the document):
  9. Fill out the relevant information. It should now look something like this:
layout: post
title: article title
authors: author/s
date: yyyy-mm-dd
tags: [“X”, “Y”, “Z”]
image: https://www.datopian.com/assets/img/blog/image-name.jpg

n.b. For preview images to show up on Twitter posts, it is important to use remote links (e.g. https://www.datopian.com/assets/img/blog/image-name.jpg) instead of local links (e.g. /assets/img/blog/image-name.jpg).

  1. Under this, leave a line and write the following code:
<!-- more -->.
  1. Under this, paste the text of your article.

  2. To add photos, use the following code:

	<img src=”./image-name.jpg” alt=”give your image a name”>
	<figcaption style=”text-align: center><a href=”link to image source”>image description for article</a><figcaption>
  1. Format your text using Markdown.

  2. In the terminal, type git push and press Enter.

  3. Type git pull and press Enter.

  4. Type git add -A and press Enter.

  5. Type git commit -m “[blog post][m]: blog post on X” and press Enter.

  6. Type git push and press Enter.

  7. Go back to the repository on GitLab and refresh the page. You should see your commit message and a completion status circle next to it. N.b. the circle should be blue when your post is uploading - this takes about 5 mins. When this turns to a green tick, your post is live on the blog. If the circle becomes a red cross, then there was a problem with your code.

# How to embed certain timeframes of YouTube videos

Sometimes, you might want to include a certain clip from a youtube video in your article to demonstrate a point.

There are a few ways to embed a certain timeframe of a youtube video clip into a web page/ blog post. One option is to embed the whole video and simply set it up to start from a particular time when you hit play. Ie. when you click on the ‘Play’ button you are instantly directed to the part of the video starting at 2:33 minutes. This option isn’t ideal because the viewer doesn’t know at which point they should stop watching the video (and might be put off watching it if it is too long).

Another option is to crop the video using an online video cropping tool and then embed only the desired timeframe. This is arguably the best option and the one we will focus on here.

In order to do this, just follow these simple steps:

  1. Copy the URL of the youtube video in question
    in our example we will use the URL of ‘NextGEOSS Datahub – Introducing CKAN’ video - https://www.youtube.com/watch?v=DTJLdTrsStY.
  2. Go to https://streamable.com/.
  3. Paste the copied URL into the input field and click on ‘Go’.
  4. Pick the time frame that you want by moving the little white circles to the wanted seconds and click on ‘Create video’.

In our example we want to crop it from 09:99 - 29:98.

  1. Click on ‘Embed’ and copy the code that appears in the pop up window.

  1. Voila!
    Paste in on your web page/ blog post and you are good to go.

Then, just to make sure people have the option to watch the full video, add a link above or below to the whole URL (in our case that would be https://www.youtube.com/watch?v=DTJLdTrsStY).

Here’s an example, taken from a talk given by Rufus and posted in this article on open data:

Click here to watch the full video.

# The Broadcasting Process

It is really important to share published content through our marketing channels. This lets our clients know what we are up to and is a great way to start attracting more traffic to the Datopian website. Please see below for instructions on how to post on each channel.

# Checklist

  • Inform Datopians that the article is live by tagging @all on the general Google Chat.
  • Make sure that the content has been pushed out through all of Datopian’s marketing channels (LinkedIn, Facebook and Twitter).
  • Update the Content Publication Master Spreadsheet.
  • Keep checking marketing channels for any comments and respond to these.

# Social media

# LinkedIn

Only a Datopian LinkedIn admin can publish a LinkedIn post. To become an admin, get in touch with the ops team.

To publish a post:

  • Use the 40-60 word abstract from the blog and attach a link to the blog post.
  • Make sure that keywords relating to the article and our intended audience are tagged. For example: #datamanagement #government #datastrategy

# Facebook

Only a Datopian Facebook admin can publish a Facebook post. To become an admin, get in touch with the ops team.

To publish a post:

  • Use the 40-60 word abstract from the blog and attach a link to the blog post.
  • Make sure that keywords relating to the article and our intended audience are tagged. For example: #datamanagement #government #datastrategy

# Twitter

You need to request the login details for Twitter from the ops team.

To publish a post:

  • Create a 140 character description from the blog and attach a link to the blog post.
  • Make sure that keywords relating to the article and our intended audience are tagged. For example: #datamanagement #government #datastrategy

# Content channels

# Dev.to

Any technical articles should be posted on Dev.to.

To publish an article:

  1. Sign up at https://dev.to (you can log in with GitHub)
  2. Navigate to https://dev.to/settings/organization
  3. Paste the secret code below and click Join Organization [4a8d8d29dc59c58d1ba6bce2966b259133def381ae69f91269ebe1f36fb64dfead60563e62409671f88aa86b7b05d039dec8]
  4. Create a post on dev.to. You can copy and paste the markdown file from the Datopian website.
  5. Add tags related to the post and our intended audience. For example: #datamanagement #government #datastrategy
  6. If you use a photo as a cover photo, make sure you also add it to the main article along with the author credentials (as it is not possible to add author credentials to cover photos). Click on ‘add image’ to generate an image link that you can use in figcapture format.
  7. Publish the article.