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.
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:
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:
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.
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.
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.
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:
The maximum length is 30 characters, which includes the filename, text indicator (_a or _n), and the file extension (.png).
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:
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:
It is a good practice to keep the original screen capture as a reference if you modify it by cropping, downsizing, or editing fields.
Do not include trademark symbols in graphics. For information on using trademark symbols in Novell documentation, see the Open Source Documentation Authoring Quick Start.
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.