Hack Club jolts - learn to build real things

Search

Style guide

Jolts will be written by many people, but should read like one unified encyclopedia. i.e. every page should feel like it came from the same person. This page is the standard of what Jolts page should be (and how you can get through PR review in one go :p) It won’t cover every situation; when in doubt, copy styles of other pages, or ask in #jolts!

Titles

TL;DR: Just name what it is! Don't add 'Learn how to' etc.

  • A guide should be titled after the thing it teaches to build!
  • For example, a guide teaching you how to make a tamagotchi should be just named "tamagotchi"
  • Sentence case for titles and headings: capitalize the first word and proper nouns, our font for title, augiepixel, will show it as lower case regardless.
  • No articles up front (“Macropad”, not “The macropad”)
  • Folder slugs are kebab-case! split-keyboard, not Split_Keyboard.
Macropad: Build a tiny keyboard that does whatever you tell it to do :D
How To Build Your Own Awesome Macropad!!!

Voice

TL;DR: Always remember you're writing for another person, assume zero experience.

  • American English spelling. Gender-neutral language!
  • Please write in a style that is easy to understand.
Push each switch in until it clicks flush. Bent pins fold flat instead of entering the socket, and check both pins before seating!
Next, we simply want to go ahead and easily insert our switches!

Steps

  • Steps are not headers! The step title should be the action. Make them short!
  • Write a <Checkpoint>for each 3-5 steps!

Headings

  • Don’t repeat the page’s subject!
  • Unique within a page.

Linking

  • Ideally, you won’t have to explain a concept within a guide, you can link it with a <ConceptLink>. Which is different to <Tool> chip.
  • You can use <ExternalGuide> to link stuff that’s out of Jolts scope, or stuff that Jolt doesn’t yet have and won’t in the foreseeable future.

Numbers and units

  • Always use digits! Even if it’s a small number.
  • Units without a space unless generally it is used with a space, such as 3.3V, 10kΩ, 470Ω, 16MHz, 500mA.
  • Commas as thousands separators: 1,000.

Photos

  • hero should ideally be an image of the finished build with transparent background
  • Descriptive kebab-case filenames, like switch-soldering.jpg, not IMG_4021.jpg.
  • Please write Alt Texts for your images, they should be descriptive as well.
  • Only upload photos you took or have the right to share! They shall be CC BY-SA 4.0.

Warnings

Sometimes you might want to show something important in a noticeable box! <Warning> is for anything they SHOULD be aware of to avoid bad things: burns, shorts, lithium batteries, mains voltage, kabooms. However, it is important to not overuse warnings. If everything is a warning people will ignore them :pf:

Tags

TL;DR: Estimate for a first-timer and beginner!

  • time and difficulty should be measured against someone doing this for the first time.
  • learns lists skills that reader will use throughout the guide, it’ll link to a tool/concept.

Where this comes from

This style guide is adopted from some rules from, but not limited to:

This is in no way comprehensive, I wrote this at 3am, contributions to the style guide would be appreciated! - Anson

Are you ready? Write a guide.