Open Source Documentation Graphics Style Quick Start
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.
1.0 Getting Started
Novell sponsors several open source projects such as Kablink Vibe, iFolder, and Identity Manager Scripting. See the Novell Developer website for information about other open source projects.
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 .
2.0 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.
3.0 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.
4.0 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.
5.0 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 64 lowercase ASCII characters; do not use special characters or spaces. For example, use a-z, 0-9, hyphens (-) 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 64 characters, which includes the filename, text indicator (_a or _n), and the file extension (.png).
6.0 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, mail-stops, passwords, TCP/IP addresses, URLs, user IDs, or email 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 user names with generic names from regions around the world.
-
-
Name the file according to the approved naming scheme described in 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.
7.0 Trademarking in Graphics
Do not include trademark symbols in graphics.
8.0 Legal Notices:
Copyright © 2013 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. For Novell trademarks, see the Novell Trademark and Service Mark list. All third-party trademarks are the property of their respective owners.