Working with Attachments

Whenever you add or update attachments in the documentation, it is important to follow consistent rules.

Naming Attachments

• Any new attachment (image, document, etc.) uploaded to xwiki.org must follow the same naming rules as the pages.
• File extensions should be lowercase for improved versioning. For example, Image.png and Image.PNG will be treated as two separate attachments with separate versions.

Screenshots / Images

• Images are highly recommended to illustrate documentation content, examples. Use the documentation resources section, which provides XAR files that can be imported into your wiki to quickly set up a realistic environment, with ready-made examples for creating screenshots and documentation content.
• When having to show an example result, don't generate it (don't produce a dynamic output example), but instead always use a screenshot. A generated example could break over time.
  • For example, instead of generating the output example as {{displayIcon name="home"/}} , use an image of the output:
    

General Best Practices for Images

• If an image is part of a bullet list, align the image with the bullet text. For detailed rules and examples on how to correctly insert images inside lists, see the List Items section of the Documentation Style guide.
• When an image is followed by a detailed description of its content, it’s best to present the image first. This helps readers understand the context without confusion.
• An image has a single owning page. Needing the same screenshot on two pages means the content itself is duplicated, so fix that first (see Avoid Duplicated Content) instead of uploading the file twice: the two copies then drift apart, since re-capturing or re-cropping one of them reaches only its own page.
• Until this bug is fixed, don't reference attachments from a page in another page (for example, {{image reference="[email protected]"/}} ). If the referenced page is moved or renamed, the image will no longer be displayed. This guideline will be updated once the bug is fixed.

Screenshot Standards

• Always capture screenshots using the latest skin.
• Screenshots should represent real UI behavior: capture them while actually using the feature.
• Show only what the reader needs in order to act: the UI element the step is about, plus the nearest landmark that tells them where that element is (the panel holding it, the screen title above it, the list it follows). Crop the rest away, side panels included when the element is not one of them. The test is whether a reader who doesn't have the wiki in front of them can still tell where the action happens.
  • Exception: the first step of a how-to or tutorial. Keep more of the interface here, since the reader hasn't been oriented yet. Later steps can be cropped tight, as the reader already saw that screen in the previous step.
  • Size follows the crop, not the other way around. Pick the size (extra, large, medium, small) that matches how much you cropped, don't screenshot the whole window just to justify using extra. A full-window shot wastes most of its 960px on menus and chrome, and since it's downscaled from a wider capture, it also looks blurrier than a screenshot taken directly at the target width.
• Always capture screenshots at the exact size you will define in the size parameter (use browser developer tools to resize before capturing): crop a region that is already that wide rather than shrinking a wider capture into it, and never enlarge a smaller one. Otherwise, the image will be of low-quality.
• You must save all images in PNG format.
• You must add a red square ("255, 0, 0" RGB value) highlighting the concerned UI element(s), meaning the ones the step asks the reader to act on: on a step that says to review a list, the square goes around the list, not around the button underneath it. You may use any image editor for this.
  • Leave a small margin between the square and the element so the border doesn't overlap the content it's highlighting.
• Always insert images using the {{image}} macro to ensure consistent styling (borders, resizing, etc.). For example:

  {{image reference="someimage.extension" size="medium" alt="Some alt text"/}}

  • Use the size parameter of the Image macro to give documentation a homogeneous look:
    • extra: width of the image : 960px;
    • large: width of the image : 650px;
    • medium: width of the image : 350px;
    • small: width of the image : 150px;

Gallery Macro

• Whenever there's a need to display more than one image next to each other (e.g., to show variations- example in this documentation page), you must use the Gallery Macro to avoid cluttering the page.
• Avoid animated GIFs, they are difficult to maintain.
• Use multiple PNGs instead.
• Example:

  {{gallery}}
  [[image:image-name1.png||alt="Example alt text for image1"]]
  [[image:image-name2.png||alt="Example alt text for image2"]]
  {{/gallery}}

Updating Attachments

• Don't delete old attachments, just replace them.
• To replace an attachment, upload the new file with the same name. This will automatically create a new version of the attachment.