Style Guide

The thing is...

Here are some quick rules of thumb, before we jump into the bits that make up a thing: the metadata in the front matter, and main content written in markdown.

Every thing is an island

• try not to include links between the things. Each thing should be able to stand alone as much as possible to facilitate reuse. Navigation between the current, previous, next and related things is handled automagically by the stuff in the front matter. This facilitates reuse where things in another collection may change order or be dropped altogether.
• try not to refer to the current thing by it's number. Use the phrase "this thing" instead. If the number changes in one place, it must be updated in all places, and hence we try to keep it in the front matter only.
• try not to put generic ARDC engagement content (e.g., twitter, email addresses, etc) in the body of the thing (this kind of stuff goes in the layout). Any links to further help in a thing should be specific to that thing (e.g., link to a Community of Practice for that thing).

Think long term

• always prefer doi's for links to resources where possible
• where linking to ARDC content, try to have a non-ARDC alternative alongside it. Consider especially content from enduring organisations. Use the wayback machine as a last resort
• try to imagine this resource ageing. Don't say "imagine it's 2050"... because one day it will be
• try to refer to recent events in a way that will age well. e.g., not "The recent development of a style guide.." but rather, "The development of a style guide in 2020"
• Don't refer to things that are about to happen

Keep it fun

• Use the structure guides below to pitch at different levels... meet people where they're at
• The things are mostly written in a relaxed, casual voice. Be careful with jargon and keep it light

The things

There are two key parts for every thing: the front matter is a special section of the document containing metadata about the document, while the main content is expressed in markdown beneath the front matter.

Front matter

The "front matter" refers to the bits between two --- at the top of the thing. This is specially formatted and care should be taken if editing them, as they are expressed in YAML. For instance, extra care must be taken with quote characters, with indentation, and with certain characters at the beginning and ends of lines.

Currently each thing maximally includes front matter like the following:

---
layout: thing
thing: 9
title: "a title for the thing"
short_title: "short title"
description: |
  a lead in paragraph of text. This is used in tables of content, but is
  also inserted at the very beginning of the thing, after the title
overview:
   Getting started: "should explain briefly how to start the thing"
   Learn more: "should explain briefly how to continue learning"
   Challenge me: "should introduce advanced topics"
category: "a theme for several things"
---

Of these, layout:, thing:, title: and description: are all required, or the page will not display correctly.

• layout: thing is what generates the page with all the fancy add ons including navigation etc.
• thing: <digit> tells us where in the sequence this thing occurs. This is used to sort the things into order, and also used in references in the thing (e.g., "Go to Thing 9"). So it should be a digit (i.e., "3" not "three")
• title: <my title> is rendered at the top of the document as the title, but is also used in navigation and summary pages pointing to all the things
• short_title: <title> is a shorter version of the title. It is currently unused, but we may introduce themes (cf category) to make little lists of related things at the end of each thing
• description: ... is used as the first paragraph, introducing the thing. It is also used in generating the table of contents for all the things, and so it should be self-contained. Note that as a paragraph, there are special rules about how this is formatted in YAML (see "block scalar style, keeping newlines")
• overview: is a special section used to generate a table of contents at the start of everything thing. It is optional and it can have as many sections as you like. The sections should all be indented and include exactly the same wording as the corresponding section in the document before the colon (i.e., Section label:) and should then be followed by a lead in to what is in that section. Standard sections that ideally occur in every thing are Getting started:, Learn more: and Challenge me:.
• category: should apply to more than one thing and is used to group them together. It is currently unused and is therefore optional.

Markdown

After the front matter, the document is in markdown (or kramdown for jekyll to be precise).

Markdown is a human readable way of styling documents. This markdown is converted into the nicer looking webpage version of our site.

Sections in a thing

The typical high level structure of the markdown looks like this in markdown:

## Getting started
### Ready, steady, go

To get started on a style guide, first we need...

## Learn more
### Now we're cooking with gas

You get the basics. Let's go a bit further...

## Challenge me
### So you think you can write a style guide...

Maybe this isn't your first style guide, but did you know that...

There are three standard sections : "Getting started", "Learn more", and "Challenge me" in each thing. These are immediately followed by a second heading expanding a little on what is in each section. These sections align with different levels of competence. Ideally, it should be possible to skip ahead, if the reader has some familiarity. The sections should build upon each other, without depending on the outcome of previous tasks.

You can change this basic structure, but try to aim for consistency across all the things in a collection, or at least be wary of breaking conventions otherwise in place across all the other things in a collection. The last thing (and possibly the first) may be points at which you can break with this convention.

You can break the sections up into multiple subsections, but be mindful of keeping the sections relatively brief and balanced. If you start to develop lots of subsections, maybe you need to break apart the thing?

Keep these things in mind:

• What goes in the front matter, stays in the front matter

  Don't include a title, introduction or overview for the the thing. These go in the front matter.

• Stick to the right levels of heading

  Only use second level (##), or third level headings (###). For consistency across all the things, don't use ='s or -'s for headings (if you don't know what that is, then don't worry!). Don't do sub-sub-sections (i.e., don't use ####)!

• Don't include navigation

  Don't put generic navigation content (i.e., don't say "jump forward to [Learn more](#learn-more)" as that is inserted automagically throughout the document. Link to other sections within a thing only if particularly relevant (i.e., "we look at this in greater detail [later on](#challenge-me)").

  Navigation (generated by the overview in the front matter) only links to the core sections. This is indicative of how each section should be a relatively self contained part of the thing.

Lists in a thing

Bullet points or numbered lists are very common in the things. Try not to go overboard on these though, and be consistent in differentiating the two. Numbered lists are for an ordered sequence of tasks (e.g., "work through the problem in this order:"), or a set of alternatives which you want to reference (e.g., "choose between (1) and (2) below..."). Bulleted lists are for an unordered set of points (e.g., "check out these links for further info:" or "these are the reasons why you should do this:").

Lists can be indented, but it's possible you'd get your point across better in prose. Avoid them if you can. You can also mix the two types (e.g., bullet points within a numbered list), but try avoid this if you can.

Here's how the lists look in markdown:

To make a numbered list you must:

1. make sure there's a blank line above the list
2. put a number and a full stop at the start of the line
3. watch as it is magically transformed into a number list

Some useful uses of lists:

- to quickly summarise some points
- to give sets of possibilities

You might like to do either (1) or (2) below:

1. Read more about [how lists are formatted](https://kramdown.gettalong.org/quickref.html#lists)

    or,

2. Keep your lists to a minimum

   Note that indentation and a line break keeps any paragraph formatted within that point. This works with bullet point lists too.