A style guide is a set of standards for creating content in a consistent way, usually written content.
SkilStak Style Guide
As the number of writers and other contributors to skilstak.io grows the need for a style guide has increased. More than just voice, word selection, and formatting this guide includes guidelines for keeping content accessible, searchable, succinct, and well organized.
skilstak.io replaces a textbook but most of the expectations of a textbook remain:
- must be legible and clear above all else
- must be optimized for reading
- must be accessible to everyone
- must keep emphasize on the content
- must not contain too many distractions
- must be printable
- must be voiceable
- must not depend on interactivity
Imagine that at any moment during browsing session a learner or teacher might want to print what they see. This means CSS print styles are optimized to actually print in black and white. It means that copyright footers are included in the content of every page and not just visually added to the bottom of the screen. It means that code snippets must be under 60 characters wide so they don't get truncated when printed.
Use an informal but respectful voice.
Imagine you are carrying on a conversation or mentoring the reader in person. This makes content compatible with spoken conversational user interfaces. We want users of our content to feel welcome and engaged at a personal level.
- Use you over one.
- Y'all is a bit to informal.
- Use we instead of I.
Write as if you are speaking to an average 9-year-old who can read Harry Potter comfortably.
💢 Authors often stuff unnecessary vocabulary into their learning content—especially college textbook authors—probably to pomp up what they perceive will be a more authoritative impression of them. It's just stupid. It shows utter disrespect for the reader who is learning.
Hey authors, no one will think you less intelligent for using simple words when writing learning material. Blah for Dummies heard of it?
Reserve your artfully-crafted words, rhetorical devices, and for that novel you've been neglecting again. Apply your considerable literary acumen there instead—where people will actually appreciate it. 😁
Web should be capitalized when referring to the Web. There are many other webs out there.
Internet should be capitalized when referring to the Internet, which is usually. People do not often refer to other networks as internets.
Questions should be capitalized like sentences even when they are headings and titles. This is different from other style guides.
Titles and headings that are not questions should be capitalized using traditional title capitalization rules.
Repeating Heading Content
Never write assuming the reader has just read the title. Often this means repeating the title in the same way or reworded somehow. For example, when defining a term use the term to start out:
A GPU or graphics processing unit is ...
It also means restating questions if the title is a question such as in the FAQ section:
Why so many TODOS?
The reasons there are so many TODOs is because ...
The general look and feel is meant to be very similar to what someone would see in a traditional text book. Formatting standards for such things have been long established and backed by research. For example, serif fonts are much easier to read than sans-serif in any modern medium.
💢 Sacrificing legibility for any reason (but usually to look cool or more modern) is a moronic decision justified by nothing more than personal ego.
Adding a Table of Contents
If you have a lot of material in a single page (which is fine) consider adding a printable table of contents to the beginning. VuePress has a convenient
[[toc]] tag you can use.
⚠️ Be careful not to make the TOC the first thing in the page or it will be considered the BaseML summary instead of a better introductory paragraph.
Everything is written in BaseML
HTML can be used but must never be relied upon for primary content.
Lists Without Bullets
<span class=nobullets> * some * things * don't * need * bullets </span>
Which gets rendered like this:
⚠️ Make sure a blank line exists between
spantags and the list.
Much like StackExchange requires, everything written here should be self-containted. External links should be avoided and secondary. Information from those sources should be paraphrased here instead. This preserves the offline-first
Stick with the image constraints of BaseML.
Always provide a full sentence of alt text for every image. The sentence should read as if a person pulled out an image in real life and showed the image at that point in the content. For example,
"Here is an image of ... ." Don't forget full punctuation because voice synthesizers take that into account.
References and Citations
Simple include a level 5 heading called References and itemize each as an independent bullet point:
##### References * Walter Isaacson, *The Innovators*, 2014
Code and Syntax Highlighting
Rather than use popular color formatting for code syntax I have decided to stick with simple black and what as would be on a blackboard, whiteboard, or in most printed books. Not only does this make all code easy to print from any printer but it avoids the problem of forcing one specific syntax color scheme on everyone that might not work well for those with color-blindness and other color sensitive issues.
Good 'ol black and white also provides equal emphasis to all of the characters involved. Often color highlighting is designed to make some characters fade into the background more than others for a professional coder who needs to see code in that way to be more efficient. Anyone learning or discussing code, however, has the opposite requirement. These readers must be encouraged to look at every single character with equal importance to avoid missing something.
Black and white also provides a universally consistent reading experience no matter what the medium.
Coding Line Numbers
No. Line numbers distract from the code. Consider the following:
- “Look at line number 20.”
- “Look at your
Which is the most instructive and valuable when helping someone learn? The second gives much more information and causes the learner to think harder. It may not be as efficient, but it is far more useful in a learning context.
Line numbers also become problematic when dealing with line wrapping and such.# style guide