Media

Media is any form of publication or distribution that littleman.co contributes to, distributes or otherwise partakes in. Currently there is:

Articles are canonically published on the littleman.co website, but can be syndicated on any provider that allows a canonical link back littleman.co

Taxonomy

Long form (160+ character) publications must be allocated a canonical category from the following:

Type Description Publication Stream

Labs

A review of a new or experimental technology, not yet used in a production environment.

Medium

Case Study

A review of a previous technical or process intervention focussed on return on investment

Medium, Website

Technical Analysis

A general description of a technical implementation across many systems

Medium, Documentation

Deep Dive

An in depth discussion of a given technical problem and solution

Medium

Philosophy

A discussion of the underlying beliefs behind the software development

Medium, Website

Publications

General Process

When writing a (long form) post, the process is as follows:

  1. Write the post up & publish it to littleman.co.

  2. Verify the content against the Hemingway app

  3. Wait ~24 hours

  4. Re-read the content

  5. Publish the content to the distribution network

A template for writing the article is below:

---
categories: []
// Uncomment one:
//  - "Labs"
//  - "Case Study"
//  - "Technical Analysis"
//  - "Deep Dive"
//  - "Philosophy"

// Date in the form of "1970-01-01"
date: __TODO__

// A description used in search results, social media tags
description: "__DESCRIPTION__"

// How the URL should appear
slug: "__this-is-a-url__"

// A list of things that this article should talk about
//
// Try and pick ~ 4 tags. The list of previously used tags is at the following URL:
// https://www.littleman.co/tags/
//
// When syndicated, the category should be an additional tag.
tags:
  - "__TAG__"
  - "__TAG__"
  - "__TAG__"
  - "__TAG__"

// The header of the article
title: "__TITLE__"

// What GitHub issue the article is tracked by
github-issue: 11

// The path to images suitable for use with the article
//
// The images work best at 1000x420
images:
  - "/images/headers/architecting-a-software-system-for-malleability.png"

// Who contributed to the article, written in the order of their contributions.
contributors:
  - "Andrew Howden"
---

== __TITLE__

// Content

Social Media

Messages should be written approximately as so:

${ITERATION} ${TITLE}

${DESCRIPTION}

${URL}

Where

  • Iteration: A notation like [New], [Via Archive], [Repost], [Revised] denotes why the item is being posted

  • Title: The article title

  • Description: A description of the articles contents

  • URL: The URL to the article.

The terms used in the iteration mean:

  • New: The article has never been published via social media before

  • Repost: The article was recently published via social media, but not in this timezone or day

  • Via Archive: The article is an older post

  • Revised: The article is an older post that has been rewritten with more up to date content

Styleguide

Admonitions

Admonitions are used to draw a reader to a particular, otherwise unspoken tip, caveat or warning. In asciidoctor the syntax is as follows:

NOTE: This is a note

The supported admonitions and their intended usage is as follows:

Note
 Clarifications. For example: "This page is the styleguide and employs demonstration content"
Tip
 Advice. For example, "TIP is best used for the sort of additional, non critical but perhaps helpful advice"
Caution
 A warning that clarifies a thing that might not otherwise be expected

The following are available, but not recommended for use.

Important
 Content that is the "main" point of the article.
Warning
 A stronger caution

References

References are used to illustrate from where information came from. In asciidoctor the syntax used is:

This is a sentence. It has a reference which is dope^cite:[citation.reference]^

At the bottom of the article a section should appear as follows:

== References

bilbiography::[]

As much as possible, content should be referenced with links to the third party resource or material that is referenced. For this site, references are stored globally in the bibtex file.

Caution
 Do not use links to reference material. Links do not transfer to other media (such as print) well and do not provide about the information at a glance within the article.
Found a bug? Got a correction? You can edit this page on GitHub