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

Screenshot Standards

• Always capture screenshots using the latest skin.
• Screenshots should represent real UI behavior: capture them while actually using the feature.
• Always capture screenshots at the exact size you will define in the size parameter (use browser developer tools to resize before capturing). 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). You may use any image editor for this.
• 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; (used for whole interface screens)
    • 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), you must use the Gallery Macro to avoid cluttering the page.
• Avoid animated GIFs, they are difficult to maintain.
• Use multiple PNGs instead.

Web Content Accessibility Guidelines (WCAG)

Non-text content (i.e., attachments, tables, figures etc.) should contain appropriate descriptions to improve accessibility and align with WCAG guidelines.

• For images:
  • The alt parameter should be used when inserting an image with the Image macro and Gallery Macro. For example:
    • {{image reference="image-name.png" size=".." alt="A good alternative text for the image"/}}

    • {{gallery}} 
      [[image:first-image-name-in-gallery.png||alt="Image one description"]]
      [[image:second-image-name-in-gallery.png||alt="Image two description"]]
      {{/gallery}}

  • The title attribute can also be used to provide supplementary information and help users better understand the image context, but it should not replace the alt text, which remains mandatory for accessibility. For example:

    • {{gallery}}
      [[image:first-image.png||alt="Image description" title="Additional information about the image"]]
      [[image:second-image.png||alt="Another image description" title="More details about this image"]]
      {{/gallery}}

  • The caption parameter could also be used for adding brief visible content under the image, for example specifying the version of the software the screenshot was taken in. For example:
    • {{image reference=".." size="" alt=".." caption="This is a caption for the image in version x.x"/}}
• For tables, figures:
  • They should be wrapped using the figure macro along with the figureCaption macro as in Figure Macro, also providing a meaningful caption.

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.

Videos

• Try to avoid videos if they don't bring a huge value, as they're harder to maintain/update when the XWiki UI changes.
• If you need a video, use the webm format which is highly compatible with modern browsers and popular for HTML5, but also generates smaller files.
• Use the Embed macro to display a video. For example:

  {{embed attachment="ckeditor-link-autocomplete.webm" width="780"/}}

• Regarding widths, follow the same rule as for images.

Diagrams

Whenever you need to add a diagram, you must:

• Use the PlantUML Macro and use one of the supported diagram types.
• Use the bluegray theme (see the example below).

This has several benefits:

• Consistent diagram L&F across xwiki.org
• The source of the diagram is in the wiki content and thus can be easily modified (it wouldn't be the case with a screenshot of a generated diagram for example)
• Makes it easier to edit diagrams as otherwise you would need to use the same tool as the one used by the person who generated the diagram to be modified (provided he attached the source to the page, see previous point)

Example:

• URL Architecture 
• Content:

  {{plantuml}}
  @startuml
  !theme bluegray
  start
  -> URL;
  :Routing Filter;
  floating note left
    Executed as the first
    Filter in web.xml
  end note
  floating note right
    Parse URL and check if there's
    a Resource Reference Handler to 
    handle the Resource Type
  end note
  if (Resource Reference Filter?) then (Yes)
    :Resource Reference Handler Servlet;
    :Resource Reference Handler;
    note: e.g. WebJarsResourceReferenceHandler
    kill
  else (No)
    partition "Legacy Action Handling" {
      :Evaluate rest of web.xml;
      split
        :Legacy Action Servlet;
        kill
      split again
        :Other Servlets;
        kill
      end split
    }
  endif
  @enduml
  {{/plantuml}}

Here are a few tools to help produce and test plantuml diagrams:

• http://www.plantuml.com/plantuml
• https://www.planttext.com
• https://plantuml-editor.kkeisuke.com/