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!).
Check also
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.
- 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:
- Client Interviews
- Case Studies
- Briefings 3a. Technical Briefings 3b. Expert briefings
- Updates/Announcements 4a. Feature and functionality updates/announcements 4b. Projects going live announcements
- ‘About us & culture’ posts 5a. General articles 5b. Travelling Datopians photo essay
- Hobby-blogger posts
- Newsletters 7a. Bi-annual projects update newsletter 7b. Feature newsletters
- 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 | OECD Case Study Link |
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 |
|---|---|
| Tone | Case studies are not blogs and articles, but structured pieces of content that are much more formal in tone. |
| Example | Case study example link. |
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. |
|---|---|
| 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 the example. |
| 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 | Link. |
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.
Search Engine Optimization
Search Engine Optimization (SEO) is a collective of good practices that make websites smarter, cleaner and better discoverable for the web. The content writer is encourajed to follow some SEO guidelines for the article to reach better visibility on search engines. You can read more on Mozilla Developer Network SEO Definition.
Links Connections
Search engines crawls better in your website when you have relevant links. Making links to existing articles, pages and sections in the portal when writing is highly encouraged; so we can have the most interlinked articles possible.
Keywords and Alternative Title
Your content is both written and published better when choosing the right keywords. Populating your document smartly with keywords that are relevant to the article area, scenario and technologies are the good way to go. An alternative title can add more keywords to your articles metadata, therefore making it more powerful to the web.
The Publication Process
Please refer to the Publication Process.
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
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
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
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:
- Sign up at Dev.to (you can log in with GitHub)
- Navigate to Organization Settings
- Paste the secret code below and click Join Organization [4a8d8d29dc59c58d1ba6bce2966b259133def381ae69f91269ebe1f36fb64dfead60563e62409671f88aa86b7b05d039dec8]
- Create a post on dev.to. You can copy and paste the markdown file from the Datopian website.
- Add tags related to the post and our intended audience. For example: #datamanagement #government #datastrategy
- 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.
- Publish the article.
Check also