This document explains guidelines for images included in your KB documents, including standards for formatting, sizing, and displaying as well as recommended naming conventions.
In this Doc
Recommended naming conventions
Please 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/Category
- Size, if applicable
- Avoid using special characters or specific file extenions:
- 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, consider the following format for your file name:
bucky-badger-headshot-medium.jpg
The key is to be descriptive but relevant. A user should understand what the file contains simply by reading the file name title.
An example of a filename to avoid would be:
Bucky Badger's photo.jpg
Helpful Tips:
- It's important to stay consistent with your naming for ease of searching in the future. Make a decision on structure and make sure all uploads follow that structure. Also, you should share these naming convention standards with other editors and admins of your KB space.
- Separate your terms with hyphens.
- Do you regularly change the documents on your site? Consider adding a version indicator to your file name convention. Something like -v1, -v2, -v3.
Image Guidelines
- Use the .png format if possible, otherwise use one of the following file formats: .jpg, .gif., or .webp.
- If possible, try to make your images no wider than 600px. This ensures that users with XGA resolution (1024x768) displays can view your content without a scroll bar and is more accessible for smartphone users.
- 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.
- The image should be clear and readable.
- Use red outlines to highlight important buttons, text fields, or other information in images. The image below shows all document attachments outlined in red.
Tips
- Avoid over-sized and highly detailed screenshots.
- Don't take screenshots of an over-sized window if you're only interested in one button, unless you're trying to show the user where to find that one button on the screen. Crop out the part of the screen you want to highlight, and bolster it with detailed text.
- Give your screenshots descriptive names. If your screenshots are 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.
- Make sure the document makes sense even without the screenshots. Screenshots are supposed to enhance the text of an existing document. Your document should be fully comprehensible without them.
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 exessive whitespace.
- This is a better screenshot because the rounded rectangle is just right and the image size is just right for the content.
Capturing screenshots
