Open Source Documentation Graphics Style Quick Start

Table of Contents

1.0 Documentation Graphics Style Guidelines

Documentation graphics that are clear, concise, technically accurate, and unified with a standard look and feel can help you convey information professionally and can enhance understanding of the concepts they represent. Novell maintains a Novell Documentation Graphics Style Guide as its primary source for guidance about creating and using documentation graphics for Novell products. This Graphics Style Quick Start discusses some best practices from our guidelines, with special emphasis on areas that might differ from other software documentation graphics.

1.1 How to Use this Guide

Use the tips in this Graphics Style Quick Start to help your volunteer graphics contributions blend smoothly into the guides prepared for Novell-sponsored open source projects. Novell initiates and sponsors several open source projects on individual Web sites (such as the iFolder™ project) and Novell DeveloperNet®. Our technical writers typically lead the project’s initial documentation effort to ensure that quality documentation is available to the open source community. We publish the documentation for stable releases in HTML and PDF format on the Novell Documentation Web site, where it can be updated regularly as part of Novell’s ongoing documentation development. We also link to the documentation’s Web page from the project site.

Volunteers can contribute to this formal publication cycle by participating in the project’s documentation project effort. For information about contributing to a documentation project sponsored by Novell, see the Open Source Documentation Authoring Quick Start.

Beginning in March 2006, Novell-sponsored open source projects typically also provide an ongoing wiki-based documentation effort, using MediaWiki*. The issues discussed in this Graphics Style Quick Start can serve as guidelines for your contributions to the wiki-based documentation. For help with creating or editing wiki pages and for uploading and displaying graphics in a wiki page, see the following:

1.2 Guiding Principles

Generally, Novell documentation uses graphics sparingly. We have no quota to meet for the number of graphics used per number of pages. Types of documentation graphics include illustrations, screen captures, and icons.

Use the following principles to guide your decision of how, when, and what type of graphic to use, given the availability of resources:

  • Include a conceptual, solution, or process graphic in the overview chapter of your document.

    If the product has numerous scenarios for implementation, choose the most common one to illustrate. It usually is not desirable or necessary to illustrate every possible configuration or application for the product.

  • Consider your audience and the complexity of the material. For example, a User Guide might require more screen captures than an Administration Guide.
  • Be consistent. Use the same appearance, screen resolution, icons, etc. for graphics used throughout your documentation.

1.3 Managing Graphics

Insert graphics into the documents you prepare, and also submit them as separate files. Organize your graphics into a single graphics directory that contains only those graphics that are actually used in your document.

1.4 Formatting Graphics

Use the Portable Network Graphics (PNG) format for graphics. For information, see the Portable Network Graphics Web site.

Typically, a graphics designer creates the illustrations, and writers, testers, or engineers capture screens of the key tasks and interfaces in the product. If you acquire screen captures in a format other than the approved PNG format, make sure to convert the files to the PNG format before submitting them with your documentation.

1.5 Naming Graphics Files

Use a descriptive name for your graphic so you can remember its content without opening it. The name can be up to 24 lowercase ASCII characters; do not use special characters, hyphens, or spaces. For example, use a-z, 0-9, and underscores (_) when naming files.

At the end of the filename, add two characters to indicate whether there is text in the graphic:

  • Append the name with _a if the graphic contains text that might require localization. For example, prod_admin_scr03_a.png.
  • Append the name with _n if there is no text in the graphic. For example, prod_admin_icon_n.png.

The maximum length is 30 characters, which includes the filename, text indicator (_a or _n), and the file extension (.png).

1.6 Capturing Screens

Screen captures are an easy way to add clarity and interest in your documentation. They can be cropped, sized, or combined with callouts to quickly communicate specific information that is difficult to convey with only text. Screen captures should be consistent and serve a specific purpose in the document. Take care to avoid overuse.

When making screen captures, remember the following:

  • Set the desktop theme and its color scheme to the default settings for your operating system.
  • Set the desktop resolution to 1024 x 768. This helps control the number of pixels in a graphic and, therefore, controls its size so it consumes less space on servers, CDs, and downloads.
  • Crop or size down the screen capture whenever possible. Smaller screens look better in online doc.
  • Protect proprietary or private information. Do not use the real names (first and last), or the phone numbers, extensions, mailstops, passwords, TCP/IP addresses, URLs, user IDs, or e-mail addresses of actual employees or others in your screen shots, diagrams, or other graphics. Likewise, do not use real workstation, server, directory, or directory tree names. Doing so creates a high security risk.

    Avoid using names of fictional characters and public figures such as politicians, authors, musicians, and actors.

    Modify any proprietary or private information that is displayed on the screen before capturing a screen shot, whenever possible. You can also edit the graphic afterwards to replace this type of information with generic information. For example:

    • Replace operational IP addresses with reserved private IP addresses such 192.168.1.1 to 192.168.1.255 or 10.0.0.0 to 10.255.255.255.
    • Replace operational domain names with example.com, which is a domain name that is reserved for use in documentation.
    • Replace employee usernames with generic names from regions around the world.
  • Name the file according to the approved naming scheme. For information, see Section 1.5, Naming Graphics Files.
  • Save the file as a PNG file, or convert it later.

    It is a good practice to keep the original screen capture as a reference if you modify it by cropping, downsizing, or editing fields.

1.7 Trademarking in Graphics

Do not include trademark symbols in graphics. For information on using trademark symbols in Novell documentation, see the Open Source Documentation Authoring Quick Start.

2.0 Legal Notice

Copyright © 2006 Novell, Inc. All rights reserved. No part of this publication may be reproduced, photocopied, stored on a retrieval system, or transmitted without the express written consent of the publisher. Novell is a registered trademark of Novell, Inc. in the United States and other countries. All third-party trademarks are the property of their respective owners. A trademark symbol (®, ™, etc.) denotes a Novell trademark; an asterisk (*) denotes a third-party trademark.