KB User's Guide - Documents Tab - Image Guidelines
In this Doc
Recommended naming conventions
Note
Be aware that if you upload a file with the same file name as an existing item, it will replace that item.
When uploading files to the KnowledgeBase, we recommend including the following information in the file name:
- Main Subject
- Role of the File
- Size, if applicable
- Avoid using special characters or the following specific file extensions:
- The following characters and extensions are not allowed: % ' + \\ / # .. ! & .php .pl .py .cgi .php3 .php4 .jsp .shtml .sh ,
For example, if you have a JPEG image of Bucky Badger's headshot, you might write the file name as "bucky-badger-headshot-medium.jpg".
The key is to be both descriptive and relevant. A user should be able to understand what a file contains simply by reading its name. For example, "Bucky Badger's photo.jpg" is somewhat vague, especially if there are multiple photos of Bucky Badger. A more specific file name makes it easier to identify the correct file at a glance.
Helpful Tips:
- Establish a clear naming structure for all your uploads to make future searches fast and reliable. Be sure to share these standards with your KB editors and admins so everyone stays consistent.
- Separate your terms with hyphens.
- Do you regularly update the documents on your site? Consider adding a version indicator to your file name convention. Something like -v1, -v2, -v3.
Image Guidelines
-
Choose the .jpg format for images to keep file sizes small, and .png format for graphics, logos, and text to preserve sharp lines and support transparent backgrounds. Remember that text as an image, or text on images can create accessibility issues. The KnowledgeBase also supports .gif. .webp formats.
- If possible, make your images no wider than 600px. This ensures that users with XGA resolution (1024x768) displays can view your content without a scroll bar appearing at the bottom of the image and is more accessible for smaller screens, like smartphones and tablets.
- The size of the image must be under 125MB when using the the multi-select uploader in Firefox, Chrome and Safari. A progress bar will display a confirmation (or error) message. Adding images via drag-and-drop or copy/paste has a size limit of 6MB.
- You must insert appropriate alt text for accessibility purposes, unless the image is purely decorative. Decorative images should have their alt text field left blank. You can also designate a decorative image by clicking on the Insert/edit image icon on the TinyMCE toolbar, and click the checkbox for Image is decorative.
- Use red outlines to highlight important buttons, text fields, or other information in images. For example, if you are describing how to create a new subfolder of your main attachments folder, you might use a red rectangle to outline the "Create folder" button, like the example below:
Tips
- Avoid over-sized and highly detailed screenshots.
-
Avoid taking screenshots of an entire window when you only need to highlight a specific button, unless you're showing users where to find it on the screen. Instead, crop the image to focus on the relevant area and provide clear supporting text to add context and guidance.
- Give your screenshots descriptive names. If your screenshot is named kb4643_01, kb4643_02, etc, it will be very confusing to make edits to the document and/or screenshots. Find more tips on file naming conventions here.
-
Ensure the document remains clear and understandable even without the screenshots. Screenshots should enhance the written content, not replace it. A reader should be able to follow and understand the document fully without relying on the images.
Examples
- This is a poor choice for a screenshot because it's far too big for the information it contains and the rounded rectangle is too tight on the text.
- This is an okay screenshot because the rounded rectangle is just right but the image is a bit big, however, there is excessive white space.
- This is a better screenshot because the rounded rectangle is just right and the image size is just right for the content.