Writing styleguide

[badlydrawnrob]

This issue is too long!! Split into manageable chunks! Start by prioritising what, exactly, I need to do. Writing is a huge subject!

"I just let it run, because you can always rewrite, check things, find the right way to say things. If you sit and plan, you get stuck in the planning. When you’re writing a book, I find my fingers just start doing it." (Terry Prachett, source)

Just-in-time and revise as-you-go — easy to understand for beginners and just enough for serious writing. Do the next right thing. Pick a style and stick with it! You can cherry-pick some of the styles you prefer, but it's easier to pick one style guide as a base.

• [x] A refresher on quasi-academic writing.
  • Citations are helpful!
  • Long boring text isn't.
• [ ] See also source/markdown/specimen.md
• [ ] Things like the Oxford comma?

Decide a general tone, style (academic? head first) as a standard default. This can always be extended or updated for child themes.

Writing must be

1. Easy to understand and reckon with (the stupid version of future me)
2. Easy to write in Markdown (including extra html markup)
3. Work in any version of Markdown (Stick with CommonMark)
4. Easy to extend (for specific needs)
5. Looks pretty

Don't be boring

I don't need to think of all this upfront, as the main things I'm using this repo for is simple articles, the anki tool, possibly a faq or simple documentation, someday a book ... so on. It just needs a simple guideline that's reasonably fun to read (and not a wall of text).

Start super small, super simple and build from there.

• [ ] A lot of documentation and writing sucks
• [ ] Don't make me think, just enough information (and no more)
• [ ] Look at design systems and even kid's books for inspiration.
• [ ] Aim to keep the language simple
• [ ] Are you writing a programming book? A CV? An article? Documentation?

Inspiration

1. Going to print
2. Designing for print
3. Economist style guide
4. Practical Typography
5. Gov.uk styleguide (design styleguide)
6. Optical size blog post

See also:

• 20 — page breaks

• 18 — is this a bad idea?[^2]

Legible fonts

• 27

Basics

Italics

• [ ] When to use italic to highlight terms (or places, authors, titles)
• [x] Bear in mind that serif fonts are way better than sans-serif fonts for this.[^1]

I'm finding it hard to find examples in context online: the way it's actually written in the book. There's lots of quotes with images, but not so many in the original style (a thought in italics)

• [ ] When to use <i> for styling?
• [ ] When not to use <i> for visual styling?

Heavily used in Terry Prachett's work and Game of Thrones. There's also times where it may not be appropriate.

Italics for works, titles, etc — or should this be 'quotation' style? For instance, this guide has seemingly arbitrary rules for not using quotation marks on certain types of works.

Bold

Bold or italic: they're mutually exclusive

Possibly for sans-serif font to replace italic terms (ie: titles, but not thoughts)

• [ ] When to use bold to highlight terms?
  • Does it detract from the text or not?
• [ ] When not to use <b> for visual styling?

Using quotations and brackets

These also tend to change depending on country — there's a few ways to go about this ¡Vamos!

• The Economist style guide ("This is speech and 'this inside' speech")

• The Oxford style guide ('This is speech and "this inside" speech')

• The New York Times

• Paraphrasing with a citation (Harvard style)

Semicolons and dashes

• Semicolons, colons, dashes

Images

• [ ] Better figure and figcaption defaults

• [ ] #13 images
• [ ] pre inside figure (with figcaption)
  • [ ] linking to a figure (and format, i.e. fig. 1 fig.1 — description
  • [ ] figure plus quote
  • [ ] figure + figure or figure > img + img (what happens when more than 1?)
• Images styleguide (rough guide on sizes, dimensions, so on)

Citations

• [ ] Citation styleguides? (Pick one!)

General Typography

• [ ] #81

General writing

• [ ] #63

Code

• [ ] #52

Other stuff

• [ ] #54

Composition

• [ ] #51

Accessibility

• [ ] #67

[^1]: They just don't stand out very well. For sans-serif fonts I feel "this stands out" better than this stands out. Possibly "this stands out" even better. For instance the "first instance of a cited Book Title" could look like this.

[^2]: Just use Markdown and stick to basic css and regular HTML tags (that Pandoc accepts), using child themes (like Anki) which have proper templating languages for more complex stuff. There might be some scope for e-Books later!

[badlydrawnrob]

Tidy this list up, prioritise, sketch it out — DO SOMETHING :)