This section outlines the formatting standards presented within this documentation. In order to maintain continuity and quality, all pull requests must best conform to the specifics below.
Walkthroughs and conceptual articles explained.
The purpose of a walkthrough is to tell the user how to do something. They do not need to convince the reader of something or explain a concept. Walkthroughs are a list of steps the reader must follow to achieve a process or function.
The vast majority of documentation within this manual falls under the Walkthrough category. Walkthroughs are generally quite short, have a neutral tone, and teach the reader how to achieve a particular process or function. They present the reader with concrete steps on where to go, what to type, and things they should click on. There is little to no conceptual information within walkthroughs.
Function or process
The end goal of a walkthrough is for the reader to achieve a very particular function.
Take an installation page for example: Following this walkthrough isn't going to teach the reader much about working with the decentralized web or what Obol is. Still, by the end, they'll have Charon installed on their computer.
Since walkthroughs cover one particular function or process, they tend to be quite short. The estimated reading time of a walkthrough is somewhere between 2 and 10 minutes. Most of the time, the most critical content in a walkthrough is presented in a numbered list. Images and gifs can help the reader understand what they should be doing.
If a walkthrough is converted into a video, that video should be no longer than 5 minutes.
Walkthroughs are split into three major sections:
- Context to the topics covered.
- What we're about to do.
- The steps we need to do.
- Summary of what we just did, and potential next steps.
Articles are written with the intent to inform and explain something. These articles don't contain any steps or actions that the reader has to perform right now.
These articles are vastly different in tone when compared to walkthroughs. Some topics and concepts can be challenging to understand, so creative writing and interesting diagrams are highly sought-after for these articles. Whatever writers can do to make a subject more understandable, the better.
Use the following goals when writing conceptual articles:
|Audience||Knowledgeable||Requires a certain amount of focus to understand.|
|Formality||Neutral||Slang is restricted. No you / your -- explain informatively.|
|Domain||Any||Usually technical, but depends on the article.|
|Tone||Confident and friendly||The reader must feel confident that the writer knows what they're talking about.|
|Intent||Describe||Tell the reader why something does the thing that it does, or why it exists.|
Articles are separated into five major sections:
- Introduction to the thing we're about to explain.
- What the thing is.
- Why it's essential.
- What other topics it relates to.
- Summary review of what we just read.
When designing a tutorial, keep in mind the walkthroughs and articles that already exist, and note down any additional content items that would need to be completed before creating the tutorial.
Grammar, formatting, and style
Here are some language-specific rules that the Obol documentation follows. If you use a writing service like Grammarly, most of these rules are turned on by default.
The Obol documentation portal is written in American English.
The Oxford comma
Follow each list of three or more items with a comma
|One, two, three, and four.||One, two, three and four.|
|Henry, Elizabeth, and George.||Henry, Elizabeth and George.|
If you have to use an acronym, spell the full phrase first and include the acronym in parentheses
() the first time it is used in each document. Exception: This generally isn't necessary for commonly-encountered acronyms like EVM, unless writing for a stand-alone article that may not be presented alongside project documentation.
Virtual Machine (VM), Decentralized Web (DWeb).
How the Markdown syntax looks, and code formatting rules to follow.
The following rules explain how we organize and structure our writing. The rules outlined here are in addition to the rules found within the Markdownlinter extension.
The following rules apply to editing and styling text.
All titles follow sentence structure. Only names and places are capitalized, along with the first letter of the title. All other letters are lower-case:
## This is a title
### Only capitalize names and places
#### The capital city of France is Paris
Every article starts with a front-matter title and description:
title: Example article
description: This is a brief description that shows up in link teasers in services like Twitter and Slack.
## This is a subtitle
Example body text.
In the above example
title:serves as a
#tag. There is only ever one title of this level in each article.
Titles do not contain punctuation. If you have a question within your title, rephrase it as a statement:
<!-- This title is wrong. -->
## What is Charon?
<!-- This title is better. -->
## Charon explained
** are used to define boldface text. Use bold text when the reader must interact with something displayed as text: buttons, hyperlinks, images with text in them, window names, and icons.
In the **Login** window, enter your email into the **Username** field and click **Sign in**.
_ are used to define italic text. Style the names of things in italics, except input fields or buttons:
Here are some American things:
- The _Spirit of St Louis_.
- The _White House_.
- The United States _Declaration of Independence_.
Quotes or sections of quoted text are styled in italics and surrounded by double quotes
In the wise words of Winnie the Pooh _"People say nothing is impossible, but I do nothing every day."_
Tag code blocks with the syntax of the core they are presenting:
All list items follow sentence structure. Only names and places are capitalized, along with the first letter of the list item. All other letters are lowercase:
- Never leave Nottingham without a sandwich.
- Brian May played guitar for Queen.
List items end with a period
., or a colon
: if the list item has a sub-list:
- Charles Dickens novels:
- Oliver Twist.
- Nicholas Nickelby.
- David Copperfield.
- J.R.R Tolkien non-fiction books:
- The Hobbit.
- Letters from Father Christmas.
Use the dash character
- for un-numbered list items:
- An apple.
- Three oranges.
- As many lemons as you can carry.
- Half a lime.
Whenever possible, spell out the name of the special character, followed by an example of the character itself within a code block.
Use the dollar sign `$` to enter debug-mode.
When instructing the reader to use a keyboard shortcut, surround individual keys in code tags:
Press `ctrl` + `c` to copy the highlighted text.
The plus symbol
+ stays outside of the code tags.
The following rules and guidelines define how to use and store images.
All images must be placed in the
/static/img folder. For multiple images attributed to a single topic, a new folder within
/img/ may be needed.
All file names are lower-case with dashes
- between words, including image files:
│ └── proof-of-spacetime
│ └── post-diagram.png
The framework and some information for this was forked from the original found on the Filecoin documentation portal