Keep these guidelines in mind when you’re writing help content to ensure your content’s on-brand, and presents the best user experience.

Help doc creation process

For a common problem or question

1. Search help.webflow.com for existing content on the topic. 
   Note: in some cases, it’s easier to find content via Google using a site: query. E.g. site:help.webflow.com sliders
2. If an existing article is closely related, consider adding your new content to the existing article
   
3. If a new article is warranted, create an Asana task and define an assignee and a due date
4. Draft the article in a Google Doc
5. Send to Waldo Broodryk for review
   Note: Waldo may send to John Moore Williams for further review if needed.
   
6. Add to CMS and publish. Please include a link to the source Google Doc in the "Internal Notes" field in the CMS.

Could the design be more helpful?

In many cases, the Webflow UI could be adjusted to help people overcome the problem in context. In such cases, file a Github ticket to fix the UI.

For a new feature

Ask yourself the following questions:

1. Does the Webflow UI present this feature with enough clarity that there’s no point adding documentation?

• If yes, don’t write a help doc.
• If no, write a help doc. (And if you have suggestions on how the UI could improve, file a GitHub ticket.)

2. Even if the Webflow UI is clear, are there common issues people might run into?

• If yes, write a help doc focused on the issue(s). (And if you have suggestions on how the UI could improve, file a GitHub ticket.)
• If no, don’t write a help doc.

If a new article is warranted, follow the process outlined under "For a common problem or question."

Content guidelines

Article title

Most help articles are of one of the two following types: 

1. Guide

Guides are general descriptions of a native feature and its core use case(s). These should be titled according to the feature name.

Examples: 

• Sliders
• Lightbox
• Block quote

2. Tutorial

Tutorials provide in-depth walkthroughs of how to achieve a particular layout or design effect using a specific feature. These should be titled using the following structure: 

[Verb]+ing+[result]+[feature/tech used]

Examples:

• Building a pricing grid with Flexbox
• Embedding Google Docs and Sheets
• Creating meta titles and descriptions with Collection fields

General standards

• Don’t include “how to" in titles
• Don’t use “Webflow” in document titles 
• Don’t phrase titles as questions
• Don't speak in the first person.
  E.g. "Deleting your account" not "How can I delete my account?"

Article slug

The article’s slug should match the article’s title.

Keywords in titles

Place target keywords in the article title. If there are common variants of the target term, use the variants in body copy and subheads.

• Example: The article "Sliders" should include instances of "carousel" in the content.

Subheadings

If the doc requires a multi-step process, reflect that in subheadings, like so: 

Step 1: Create a new Collection

Body copy

Keep sentences short and direct. Be informative rather than entertaining. Capitalize UI elements to align with their presentation in the app.

Use the simplest word/phrase possible. E.g.:

• “go to” not “navigate to”
• “click” not “click on”
• “to” not “in order to”

Tip: Run your copy through Hemingway Editor to identify opportunities to cut/clean up copy.

Links

Embed links in descriptive, keyword-rich language, never  “here” or “learn more.” 

• E.g. “designing sliders” not “here”

You can also link to the article via its title, e.g.: See “The flexbox guide” for more on that.

Links to external sites (non-Webflow domains) should always open in a new tab.

Images

Use screenshots liberally, especially where they clarify complex UI descriptions.

Illustrate context by capturing the entire screen, and use arrows to clarify where the action’s happening.

If there’s a lot of detail where the action’s happening, subsequent screenshots can “zoom in” on the relevant area without providing context.

Make sure all images/GIFs/videos inside the the Main Doc Content field are set to a custom width of 80%. If an image is smaller than 80% of the width, it should be its native @2x size.

Always alt tag your images.

Always caption. Note that it's fine to repeat content that appears in the body copy as some people will just look through images in an attempt to understand required steps.

Video

If an article has a video, it should be embedded in "Main Video" rich text field.

See video tutorial guidelines. The most important thing to remember about using video in Help documentation is that video and text should:

1. Contain (essentially) the same content. I.e., text doesn’t need to be a straight transcript, but should solve the same issue in the same way.

Notes

For the Help site, we have two distinct forms of note:

1. Warning (block quote)
   Use the rich text field's block quote style to draw attention to common pitfalls/mistakes/things to watch out for.
2. Info (H6)
   Use the H6 style to provide "good to know" info — things that are helpful but not necessarily urgent.

Cross-references

If another help doc/blog post/video course will help someone solve the problem discussed in the current doc, link to it!

Note: In some cases, it's more appropriate to link to an external article or tutorial than to publish it on our site. Details on browser support and integration tutorials are good examples of this, because it saves us from having to constantly monitor external content and update accordingly.

Helpful, concise, personable, knowledgeable