Best Practices

This page provides a list of best practices for you to follow when building and maintaining your documentation website.

Use an editor with good markdown support

While you can edit markdown in any text editor, it helps if your editor has time-saving features for managing markdown.

If you use Visual Studio Code, check out these tips for editing markdown in VS Code.

Break your content into small chunks

Users can feel overwhelmed when looking at a page that’s full of large dense blocks of text. You can help them absorb your content more quickly and easily by breaking it into smaller chunks.

In particular, each paragraph should cover only one short idea.

One approach is to start out making each sentence its own paragraph. Then combine similar sentences into short paragraphs.

Breaking your content into smaller chunks creates a kind of visual ladder that users can quickly “climb” through your content. A good ladder has empty spaces between the rungs where a person can place their hands and feet, allowing them to move up the ladder. Without empty spaces, a ladder is useless.

So add empty space handholds and footholds in your content by breaking it into smaller chunks. This will help your users “climb” your content more quickly and easily.

Pick out key words in bold

Another way to help users move through your content without missing the point is to highlight the key words in each paragraph in bold.

This approach helps users quickly scan through the page to find just the information they need. Like it or not, they will not read every word of our documentation; but we can still help them scan until they find the right info.

Bolding the key words in your content is like adding stepping stones in a creek; they help users quickly jump through your content until they find the section that’s relevant to their needs.

Examples of making text easier to read

Check out the two following paragraphs. Which example was easier to read and comprehend? Why do you think that is so?

Example of dense text with no bolding

The first example globs all of the text into one unbroken paragraph. None of the key words are highlighted.

Example using smaller chunks of text and bolding

The second example breaks the text into multiple paragraphs. Key words are highlighted in bold, making it easier to quickly understand what each paragraph covers.

Minimize the use of HRs

You can add a horizontal separator between sections of your content by putting “—” on its own line. This generates an HTML hr, which stands for horizontal rule.

An hr is shown below:

This is supported, but you should definitely minimize any usage of it. While it may look ok on the surface, these horizontal lines act as a kind of speed bump, slowing down the user momentarily as they scan the page.

In general we should be finding ways to help the user more easily scan our content, not slow them down.

Pay attention to tone

• Use short, everyday words.
  • For example, say “steps” instead of “procedure”, and say “use” instead of “utilize”.
  • We’re trying to help the user understand what is happening as easily as possible, not to show off our vocabulary. Simpler language helps us do that more effectively.
  • Also, English may not be the first language for your user. Using simpler terms can help your documentation be more usable by all.
• Be encouraging.
  • Help the user feel empowered.
  • For example, say “you can” instead of “the product lets you”.
• Be user focused.
  • The user may be frustrated with us, so assist them compassionately instead of talking down to them.
• Use active language.
  • For example, say “Press the button to…” instead of “When the button is pressed…”.
• Use positive phrasing when possible.
  • For example, say “Fund the loan before closing the application” instead of “Don’t close the application without funding the loan”.
• Don’t try to be funny.
  • Cutesy messages can come across as unprofessional or annoying. (“Oops, looks like that darn server’s down again, lolz!”)

Use inclusive language

Consider using inclusive language in your documentation. We want all people to feel welcome and comfortable when they use Jack Henry products and services. Using inclusive language helps us to achieve that.

You can learn more about inclusive language here: https://www.apa.org/about/apa/equity-diversity-inclusion/language-guidelines

Have the text reviewed

Have technical writers or editors review all user interface text. They can help you find and correct any problems in your user interface text.

Users may see typos and grammar problems as a sign of phishing and other malware. This can reduce your users’ confidence in your application.

Also, overly complex and poorly worded messages can make it more difficult for users to understand what is happening.

Follow the Jack Henry Style Guide

The Jack Henry Style Guide provides guidance on technical documentation for Jack Henry products. Some portions of this can be a good reference to use when writing your doc.