Learn how to write guides and organize them into topics.
Your profile is located here: u/(username). From this page, you can create and manage one or more topics.
When creating a topic, you should think about what makes you a credible resource in that topic. Why should someone looking to learn within that topic choose your content?
Topic names should strike a balance between broadness and niche. For example, technology may be too broad of a topic as it could encompass many sub-topics. python-programming could be seen as too niche. If your content is primarily about coding, a balance could be software-engineering.
Also, keep in mind that the topic you choose may cross into another field. For example, if you choose project-management, it could encompass project management in a corporate setting or in construction. Be aware of names that are present in both industries.
Keep in mind the following:
Under each of your topics, u/(username)/(topic-slug), you will have the ability to create and view guides under that topic.
When clicking/tapping "New Guide," you'll be prompted to fill out some initial details about your guide:
Upon clicking "Continue," your guide will be created, and you will enter the guide editor. The next sections provide additional information on the guide editor and writing your guide.
The guide editor is the interface used to edit the content of your guide. Let's start with the top menu bar.
From left to right:
Autosave: As you work on your guide, it will automatically save as you go. Any updates to the name, tags, and description are published automatically during autosave.
Publishing Updates: In most situations, you will work on the contents of a guide (Sections and Steps/YAML) over time, and only when complete would you want to publish it. Any updates to the guide YAML are not published unless the "Save and Publish" button is clicked. If you view one of your guides and there is a difference between what is published and what is still in draft, you will see Unpublished changes at the top of the guide.
First Time Publish: When a guide is published for the first time, it is no longer possible to update the guide slug. Anything else about a guide can change, except the slug, on all future updates.
Auto Unlisting: Guides are automatically unlisted if there are no sections or steps associated with them. This ensures that the guides available to users contain actual content.
The bottom half of the Guide Editor contains two sections. On larger screens, you'll see the YAML editor on the left and a preview pane on the right. If you are on mobile, you will be shown tabs to flip between the two. Let's go over each of these:
(Left) YAML Editor: The YAML Editor is where the contents of your guide are written as sections and steps. The next section goes over YAML in detail, and the Reference Guide provides examples of content you can use. As updates are made here, you will be provided with feedback or a preview on the Preview pane (right side).
(Right) Preview Pane: The Preview Pane provides feedback as you edit the contents of your guide in the YAML editor. In addition, clicking on help or example tabs will display additional content in this pane.
YAML (YAML Ain't Markup Language) is a markup language (like HTML), but instead of structuring web pages, it structures data. Don't get bogged down in the coding aspect of it; if you can write a grocery list, you can write YAML. This guide will focus on the basics: key-value pairs (think of how a dictionary works), lists, booleans (if something is true/on, false/off), and multiline strings (text). This is enough to know how to create a guide.
Key-value pairs are the fundamental building blocks in YAML. Each key-value pair is written on a new line, with the key followed by a colon and the value:
name: John Doe
age: 30
city: New YorkLists can be defined using a dash followed by a space. Each item in the list can be a simple value or a more complex object with its own key-value pairs:
fruits:
- Apple
- Banana
- Orangeemployees:
- name: John Doe
age: 30
department: Engineering
- name: Jane Smith
age: 25
department: MarketingBooleans are straightforward in YAML. They are written as true or false:
is_active: true
is_admin: falseMultiline strings can be written using the pipe (|) or the greater-than (>) symbol. The pipe (|) preserves newlines, while the greater-than (>) symbol folds newlines into spaces.
description: |
This is a description that spans
multiple lines. Each line break
will be preserved.summary: >
This is a summary that spans
multiple lines. Line breaks will be
folded into spaces.Here's an example that combines key-value pairs, a list of objects, booleans, and multiline strings:
project:
name: Example Project
version: 1.0
description: |
This is an example project.
It demonstrates various features
of YAML.
contributors:
- name: Alice
role: Developer
active: true
- name: Bob
role: Designer
active: false
tags:
- yaml
- guide
- exampleWith this guide, you should have a good understanding of how to write YAML. The next section provides examples and references specific to writing guides.
Use this guide and the associated YAML (use the tabs at the bottom to swap between the two) to see how to create any part of a guide.
Each step can be styled with an icon. Icons consist of icons from Google Font's Material Icons or an emoji. Background colors are any of the colors defined by Tailwind CSS's Color Palette. Emoji are always rendered as they appear in Google's Noto Color Emoji Library.
Let's look at some examples of how to style icons.
icon: 📃 bg-sky-900When specifying a background color, it's done as bg-(color name)-(number).
icon: material-cooking bg-green-600When using a material icon, prepend it with 'material-' and then the icon name: material-(icon_name).
icon: 🧑🚀 bg-sky-900Google's Emoji set also includes emojis that can be created by combining two emojis.
icon: material-heart_check bg-rose-800Some of the material icons use two or more words; if this is the case, only the icon's name uses an underscore.
The answer to what makes a good guide can be fairly subjective. As a Smee writing a guide, your role is to provide direction and clarity on a topic that those reading your guide may know little to nothing about. Ask yourself: How would you start again? What resources are important for a well-rounded understanding of a topic, and what bits of wisdom can you provide along the way? A guide is also a place for you to organize all those great bookmarks you’ve collected over the years and present them in a new way.
Think about writing the guide you wish you had when you were learning a topic: the order you wished it was presented in, and the tips and insights someone might have provided you along the way. Ultimately, how you write your guides is up to you. However, here are some tips and general guidelines to make your content as approachable and useful as possible:
By keeping this philosophy in mind, you’re bound to help learners and information seekers navigate their way through a subject. The next time someone asks, “Hey there, I’m looking to get into _____ as well. Do you have any tips you can share?” you’ll be ready for them.
SmeeGuides aims to be a place to find guides and wisdom on nearly any topic. There are some topics and content that are prohibited. For complete details, see our User Agreement. But here are the big ones to keep in mind: