Skip to content
Design System

Help Center articles

Organization

When organizing the Help Center, there are six basic types of articles that should be used:

  • About - this is a module/feature overview that provides a high-level overview of the functionality/area, including what type of users will benefit from its use.

  • Video - this should contain a long video or series of short videos that illustrate how (and why) users should use a feature in their app. Videos can also be used to recap relevant information from short webinars like Office Hours or long videos like the What’s New release webinars.

  • How to - this is a step-by-step article that teaches users how to use the product to execute certain actions in the app. It can contain multiple sections, or it can be limited to a very specific function or report.

  • What’s New - this is a release article that contains highlights, links, and downloads so users can learn all they need to know about what is in a product update.

  • Featured Article – the purpose of this type of article is to highlight specific benefits of a report, feature, or module to the user and provide information on the value to the user. These are written in blog style, sort of like a blog for customers only instead of for the general public.

  • Troubleshooting - to help clients uncover the root cause and remedy common issues they encounter, use this article type. Be sure to include obvious key terms that a user might search, like part of the error code or message, when creating this article type.

Naming an article

Article naming should follow a naming convention for each article type.

  • About – These are feature or module overviews, so they should be titled broadly, eg “Introduction to Analytics” or “The Analytics Module: Validation Reports.”

  • Video – Begin each article with the type of video article it will be, whether it is a video tour, a webinar recap, or an office hours short. How to and About articles that contain videos do not follow this convention. For example, use “VIDEO TOUR: Name of feature or action” or “WEBIANR RECAP: Name of webinar” as names for Video articles.

  • How to – Start the article title with an action word, like Using, Creating, Finding, Fixing, Managing, Tracking, Generating, Setting up, etc., followed by a short description of the action being completed. For example, ""Finding your Data Package in Veeva"" would show Data Exchange users the steps for locating a validated Data Package in the Veeva Vault.

  • What’s New – These release articles should be titled the same way, “What’s new in Software Version X.X.X”

  • Feature article – These articles should be titled with a headline feel – the goal is to draw users in so we can demonstrate the value of a feature’s or module’s use, convey the importance of a more complex concept, or a highlight industry and workflow best practices. If the article were a blog post, what would an engaging title be for it? That’s the feeling you want from these article types.

  • Troubleshooting - Users who may be frustrated by a common error want to be able to find help quickly, and by including an error code or part of an error message in the article title or description will narrow the search and help them find what they need quickly.

Creating an article

To publish a client-facing Help Article, you must have rights to manage articles.

Anatomy of an article

Articles should typically follow this format with few exceptions:

  • Title: This is displayed at the top of the article and in the list of articles within the Help Center. Make it clear but succinct, following the naming conventions above.

  • Summary/Description: This offers a bit more about what information a reader can expect to obtain from reading the article.

  • Intro paragraph: This friendly introduction should contain two key pieces of information and consist of 1-3 sentences. It should explain what the feature/module is and what it does and why using it provides benefit to the user. For How-to articles, it can also give a summary of which how-to steps will be found in the article if needed.

  • Article body: The meat of the article provides specific, in-depth information for the reader to learn about a concept, module, industry best practice, or feature. Using sections to break content into digestible bits, numbering steps to provide order, and adding bullets to make information easy to scan for a reader are all ways to effectively convey information within these articles.

  • Article footer: Provide links to related articles so that readers can self-help if the current article did not answer their questions. In addition, provide readers with information on how to reach customer success or support teams if they need guidance that the Help Center cannot provide.

Pro tips and best practices for article bodies

Follow the Design System Design Principles for capitalization, brand names, etc. For Help Articles in particular, beware of:

  • Referral URL: If a Help Article is created for specifically linking in-app, omit the steps before that page or keep them brief – you can always link to the prequel in the article’s paragraph. The User is there, so tell them what to do next.

  • Screenshots: Should be high resolution and use the big FontAwesome cursor. Do not use an outline, but you can use a subtle drop shadow. If captioning, keep the caption short and simple.

  • Space between elements: Use one hard carriage return to separate elements. This will prevent too much white space.

  • Video: Most Help Centers, such as the Intercom tool currently used by several Certara applications, allow you to add video to an article using an embedded URL (which it inserts into an iframe for you). Video first must be hosted somewhere – P21 uses Wistia – to have a URL to embed.

Text and content formatting

  • Headings: Use H1s, structured with a relevant emoji. Avoid the use of H2s (and definitely H3s) unless you really need to break up a section into subsections.

  • Version note: If the application allows for a customer to control the deployment of newer versions to their environments, you may want to include a note about which version a feature is introduced.

    • Example
      Note: This Help Article applies to P21E 5.4.0 and higher.

  • Capitalization: Capitalize product-specific artifacts. For example, P21’s Define Designer should be capitalized, but “creating a define” would not be.

  • Use of bold: Bold should be used to draw attention to only the most important words in the most important bits of content.

  • Bulleted and numbered lists: Try not to go to one level deep at most. Bullets are used to highlight important information and make it more scannable, where numbers are used to lay out the steps a user will take to complete an action.

  • File extensions: One their own, file extensions should be in all caps, such as XPT, XLSX, PDF, etc. When including a file name, extensions should be lowercase, such as in define.xml.

  • Hyperlinks: Link meaningful words, not things like here or this. Less is more, so try to limit hyperlinks to 5 per Help Article (otherwise, the CTAs dilute), and cap screenshots to 3 per Help Article (otherwise lots of scrolling). If you need more than five, consider breaking the long article into two shorter ones. Hyperlinked text should be a normal text font weight (not a headline) and color (Intercom defaults to a standard blue to indicate the text is clickable).

  • Capitalization of hyperlinks: Hyperlinked text in the Help Center should follow the standard rules for the brand, sentence case unless the text is an article title, located at the beginning of a sentence, or a named, product-specific component.

  • Tables: Lay out content in sensible columns when necessary to present technical or comparison information or place an image next to descriptive text. Tables should not contain any background colors and follow the same text formatting rules listed above.

  • Dropdowns: When publishing lengthy lists by category, use the dropdown feature to allow a user to expand or collapse them to limit the amount of scrolling needed to locate information and resources. Content in collapsed dropdowns will still appear in search.

Tips for using images:

Some Help Centers do not allow images to float next to text, so keep that in mind when placing an image - it will stand alone on its own “line” with text either above or below. You typically have the option to align the image with the article’s left margin or center it.

Images should be at least 72 ppi. Keep in mind that larger image files may take longer to load, which leads to a poor customer experience.

Adding a description to an image accomplishes several things:

  • The image becomes searchable through the terms used in the description.
  • Screen readers can translate what the image is for visually impaired users.
  • If the image appears broken, the image description still indicates what the user would be seeing.

Attaching documents

Some Help Center tools allow you to attach documents to an article. To draw special attention to a specific download that is hosted somewhere, use a button in the article and link it to the document IRL.

You can also hyperlink text to a document.

Organizing collections of articles

When creating a new help center, it is important to develop an outline or hierarchy for your Help Center articles to keep them organized for use now and into the future.

Approaches to setting up a hierarchy may vary, but grouping articles by module or function is a smart strategy. This way, all articles related to a certain module are together, and then the specific features can be grouped again into subcollections.

An example of this in the P21 Enterprise Help Center is for the Validation & Issue Management Collection. While the general functionality of both Validation and Issue Management is directly related and therefore housed in the same Collection, the articles are divided into two subcollections to keep the list for each smaller and more focused.

Congratulations! You have successfully improved the information accessible to the client!