Style Guide

Summary: Runcible is a rich and deep product, and this Guide is detailed.

Runcible is a rich and deep product, and this Guide is detailed. Because it's detailed, we styled the document to satisfy the goal of

making it easy for you to scan through it, and to find what you want to, without a lot of reading.

Heading 2 is for Topic Headlines - Usually Provided by the Page Title

Heading 3 is for Subtopics that you use to introduce using a Question form

Heading 4 is for Subtopic Headings, and all other headings under it. Options(what), and Actions (how), Stated as a Question.

We start off any section that contains subsections with an introduction.

Then if possible or useful, a list of the subsections as a menu of links to the content that follows.

[alert style="grey ml60"]

For a Sub-Menu we use the Grey Alert Style using the Alert Shortcode and ml30, ml60, ml90, ml120 to indent it. • So that it's clear to users that these are links • So that it's clear to users that these are links • So that it's clear to users that these are links

[/alert]

Standard Section Headings are:

What is the purpose of this thing?

A list of topics here.

What do I see on the Display?

A list of topics here.

What actions can I take?

[actionbadge] An Ordered list of actions from the most basic to the most complex.

A list of topics here. Notice we use the 'actionbadge' shortcode before user-actions so that they're easy to separate from informative text.

[actionbadge] With each action in H4 Like This

To Describe A List of Actions we use hard returns (paragraphs):

• Indented and Bulleted Text...

• To describe a List of actions...

• That the user can take.

So that each step is easy to see with the human eye.

But for simple lists that are not actions, we use soft returns:

• And for just a list of things • We don't separate them into paragraph lines • But just use a soft return.

Then We Use Bold Text To introduce a paragraph of text.

Images: To assist you in quickly understanding the context just by scanning.

Proper Case Names: Of Runcible objects: Like the "Workspace", or "Tasks."

Bold Text: To assist you in scanning quickly through text for context.

Text: We try to confine to the basics: options (What) you have and things you can do (How).

Blocks: And we use block-quotes for information beyond the basic:

Note: Notes supply additional information: Who, Why, When, Where, What Else, What Not to do. Tip: Tips suggestion ideas on how to do something better, or more advanced. Hint / Why?: We draw attention to something that might not be intuitive Tidbit: Some editorial background from the team on why we did something, or our personal experience.

Videos: Tutorials that help you understand by doing.

Question and Answer Sections Look like This in H4 (Answer: What Problems Might I Encounter?)

What do we do in the question and answer sections?

We use sentence case in bold for each question, and an indented answer like this.

How Do We Organize Page Content?

In Each Guide, We Use Sections (Topic Pages) and Content Blocks ( Reusable Text)

We Build the Guide(collection of Pages in a hierarchy

-> Using Sections (Pages)

-> That Include Content Blocks (text that can be dynamically inserted into pages using shortcodes).

How do we choose Topics vs Subtopics?

We try to use one page per topic.

We can place multiple topics on a page if:

Opening the topics together in single-page context assists the user, or not doing so would confuse the user AND It is unlikely that the user will search for the topic for its own sake.

When placing multiple topics on the same page: We insert a Horizontal Rule between them.

Many sections and subsections refer to similar or duplicate content.

Our intention is to get the user to a page and fully answer his or her needs on that single page, without loading another one.

This means that we duplicate instructional content throughout the document.

We duplicate content using Content Blocks, and then insert these blocks into the pages where we want to present them.

If a user might search for that content exclusively, then we will break it out into its own page, and link to it.