Writing styleguide: code and tabular data

[badlydrawnrob]

Writing and compiling

• Tidy up build scripts? #24 (they're mixed and messy at the moment)
  • A simple way to write and compile an article or a blog.
  • A simple way to generate a pdf or presentation.
  • Just use Pandoc?

Monospaced fonts

• Remove colours from inline css #64 (and check <code><strong> inherited styles)
• Typography stack for system fonts #31
• Rename the --code-color variables? #57

Code examples, references, images

• How to structure internal/external links?
  • Ease of reading, less distraction, yet Brutalist.
• code inside other elements? h1, blockquote, etc
  • Or, make a note never to use within elements whose font is bigger (easier)
• Pandoc's fast-reading of isolated documentation snippets
  • Only downside is a bit hard to find the exact snippet you need (poor search/list)
• Table of contents for longer articles
  • e.g: Real python, HTDP, Ben Frain
• Reliable (MD compiler agnostic) footnotes or references (see Economist style guide)

Insert and delete

• ins, and del vs s?

Tables, instructions, lists

See here and here

• Tables with and without headers (what are the semantics)
  • Section headers?
  • Real headers?
  • Style table headers?
  • Or, use a data list (dl) if there's no need for column / row headers?
  • Longer content, other content

Maths (unlikely I'll use it)

• Maths and symbols (not <code>)

[badlydrawnrob]

Pandoc example

Main website

For me the main section of the website doesn't always do a good job of leading users to the content they need for a task.