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
- 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
- If an existing article is closely related, consider adding your new content to the existing article
- If a new article is warranted, create an Asana task and define an assignee and a due date
- Draft the article in a Google Doc
- Send to Waldo Broodryk for review
Note: Waldo may send to John Moore Williams for further review if needed.
- 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."
Most help articles are of one of the two following types:
Guides are general descriptions of a native feature and its core use case(s). These should be titled according to the feature name.
- Block quote
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:
- Building a pricing grid with Flexbox
- Embedding Google Docs and Sheets
- Creating meta titles and descriptions with Collection fields
- 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?"
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.
If the doc requires a multi-step process, reflect that in subheadings, like so:
Step 1: Create a new Collection
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.
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.
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.
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:
- 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.
For the Help site, we have two distinct forms of note:
- Warning (block quote)
Use the rich text field's block quote style to draw attention to common pitfalls/mistakes/things to watch out for.
- Info (H6)
Use the H6 style to provide "good to know" info — things that are helpful but not necessarily urgent.
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
Nice! This totally solves my problem, and it's a lot easier than I thought it'd be.