Topics Map > Documents Tab

KB User's Guide - Documents Tab - Image Guidelines

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:


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.

  • 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.

  • Unfortunately, this does not work in IE, so IE will not have any multi-select feature and is still limited to 40MB files.

  • 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.

    doc attachment folder on the edit screen_select attachment to emebed into doc from here


  • 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.

  • Save images in formats of PNG, JPG or GIF.

  • 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.

  • 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.


    giant screen shot with a lot of white space_horrible example

  • 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.

    medium sized image still with excessive whitespace

  • This is an okay screenshot because the rounded rectangle is just right but the image is a bit big, however, there is exessive whitespace.

    ideal sized image with precise information highlighted with a round cornered rectangle

  • This is a better screenshot because the rounded rectangle is just right and the image size is just right for the content.

Capturing screenshots

Keywordskbadmin knowledgebase tools users guide screenshots guidelines help format rules images image picture pictures missing alt tag tags text file naming upload attachment attachments folderDoc ID4643
OwnerLeah S.GroupKB User's Guide
Created2006-04-27 19:00:00Updated2023-07-25 13:32:35
SitesKB Demo, KB Demo - Child Demo KB, KB User's Guide, Social Science Computing Cooperative
Feedback  1   0