Open Source Documentation for Novell Forge Projects

w w w. n o v e l l . c o m

Novell

February 15, 2006

Q U I C K S TA R T

Documentation Projects on Novell Forge

This guide provides the basic information you need to contribute documentation for a Novell Forge project. Section , What Is a Documentation Project?, on page 1 Section , How Can I Contribute?, on page 2 Section , Logging In to Novell Forge, on page 2 Section , Finding Your Project, on page 3 Section , Volunteering for Documentation Tasks, on page 3 Section , Downloading the Documentation Source Files, on page 4 Section , Understanding the Documentation Source Files, on page 4 Section , Creating New Documents or Graphics, on page 5 Section , Modifying Existing Documents or Graphics, on page 5 Section , Using Content and Style Conventions, on page 6 Section , Ensuring the Technical Accuracy of Your Documentation, on page 6 Section , Submitting Documentation, on page 6 Section , Providing Feedback for Existing Documentation, on page 7

W H A T I S A D O C U M E N T A TI O N P R O J E C T ?
Documentation projects provide the framework for developing, publishing, and maintaining the product and developer documentation for their related developer projects on Novell Forge. Most major Forge projects have corresponding documentation projects, but not all do. Documentation project members include both Novell employees and volunteers from the open source community. They collaborate to write, publish, and maintain a variety of documents in multiple publication formats. An editor manages contributions from volunteers and coordinates the publication process. Usually, the senior editor is a technical writer from Novell who is also responsible for publishing a Novell branded version of the documentation. Trusted contributors can also serve as editors.

H O W C A N I C O N T R I B U TE ?
Your participation and contributions are welcome. You can help in any of the following ways: Contribute product documentation for new features, scenarios, frequently asked questions (FAQs), troubleshooting tips, or user tips and tricks Contribute developer documentation for new APIs, technology white papers, FAQs, or developer tutorials Contribute documentation graphics such as illustrations of concepts and processes or screen shots of critical interfaces Report problems in and provide constructive feedback for existing documents, using the User Comments section of the online documentation Localize existing documentation Separate Quick Starts are available that discuss documentation style, graphics style, and localization guidelines for your contributions to open source projects on Novell Forge.

LOGGING IN TO NOVELL FORGE

To participate in a documentation project on Novell Forge, you need a Novell Login account. Registration for an account is free, but you must provide some basic personal contact information to create your personal user profile. Log in to your account whenever you participate in mailing lists or activities related to your Novell Forge projects. For example, you must log in to your account to upload and download the source files for documents. If you do not have a Novell Login account, create your personal user profile: 1 In a Web browser, go to Novell Forge (http://forge.novell.com). 2 In the Login area, click Register Now to open the Novell Account form. 3 Type your personal information, making sure to complete all items marked as being Required (* or +). 4 Click Next. The username and e-mail address you submit must be unique. If they are not unique, Forge returns an error message. Type a new value, then click Next. If they are unique, Forge creates a unique, secure Novell Login account for you. 5 If you use Novell products, specify your Support Credentials and Channel Order Tool Credentials, then click Finish. To log in to your Novell Forge Login account: 1 In a Web browser, go to Novell Forge (http://forge.novell.com).

2 In the Login area, type the username and password for your Novell Login account. 3 Click User Login. 4 If a Security Alert message warns that you are being redirected to a insecure connection, click Yes to continue. The warning appears because you are being redirected back to the Novell Forge main page. You can log out at any time by clicking Logout in the Forge main toolbar in the upper right corner of Forge pages.

F IN DI NG Y O U R P R O J E C T
After you log in to Novell Forge, locate the project where you want to contribute: 1 In the left navigator, find the Search area, then do one of the following: Type one or two keywords about your project, then click Search. The search engine displays a prioritized list of all Novell Forge projects that correspond with your search criteria. Click View Project List a-z, then locate your project by name from the alphabetical listing. Click View Project Categories, then locate your project by category and then by name from the listing. 2 From the resulting search list, click your project's name to open the projects Summary page. 3 To access documentation for your Forge project, click Docs in the project toolbar.

V O L U N T E E R I N G F O R D O CU M E N T A T IO N T A SKS
The documentation team members with Editor rights maintain a Doc Tasks list to keep track of major tasks that need to be done and to help new contributors find out how they can help. The list shows the current documentation requirements for the team, who is working on each task, the delivery schedule, and the priority assigned to each task. Before you begin working on any documents for your project, review the Doc Tasks list and coordinate your interests and efforts with the Documentation Editors and other team members. Even assigned tasks might have subtasks needing attention, so it is useful to inquire about particular tasks that interest you.

Accessing the Documentation Tasks List

On the Docs page for your Forge project, under the Doc Project group, click Tasks.

Subscribing to the Mailing List

Subscribe to the Project-Dev mailing list to learn more about the project, key players, and to correspond with the Documentation Project editors. The Project Mailing Lists page provides

access to mailing lists for the project. You can read current and archived messages online or subscribe to the list to have new messages delivered to your e-mail account. 1 From the project's Summary page on Novell Forge, click Mailing Lists. 2 Subscribe to the Project-Dev mailing list, where Project is the unique name or acronym used for the project.

Volunteering for a Documentation Task

Send an e-mail to the Project-Dev mailing list, detailing your interests and availability in helping with the documentation project. For information, see Subscribing to the Mailing List on page 3. A documentation project editor typically replies within five business days to discuss your interests, assign a task, and coordinate a delivery schedule, as appropriate for your query.

Submitting New Tasks

To recommend new documentation tasks to the documentation team, send an e-mail to the Project-Dev mailing list. For information, see Subscribing to the Mailing List on page 3.

D O W N LO A D IN G TH E D O C UM E NT A T I O N S O U R C E F IL ES
After you accept a documentation assignment, you can download all relevant documentation source files for your project. If you are creating a new document, download the source files of a similar document to familiarize yourself with the style and format you are expected to use. 1 Log in to your Novell Login account. 2 Go to your project's Docs page. 3 Scan the list of available documents and locate the zip file that contains the source documentation files. 4 Click the file to begin its download to your computer. 5 Extract the documentation source files to your workstation.

U N D E R S T A N D I N G T HE D O CU MEN TA TI O N S O U R CE F IL ES
Your Novell Forge documentation source file download contains several different types of files. XML files in DocBook XML standard markup format For information, see the DocBook.org Web site (http://www.docbook.org) or the Organization for the Advancement of Structured Information Standards (OASIS) DocBook Technical Committee Web site (http://www.oasis-open.org/committees/ tc_home.php?wg_abbrev=docbook). From the XML files, Novell applies its documentation style sheet to generate viewable and downloadable HTML and PDF files.

 PNG files in standard Portable Network Graphics format For information, see the Portable Network Graphics Web site (http://www.libpng.org/pub/ png/). Other graphics files Some documentation might have existing graphics in Extended PostScript* (EPS) file format or the Graphics Interchange Format* (GIF*) file format. Conversion from EPS or GIF file format to PNG occurs when modifications to a graphic's content is necessary. No new graphics files use EPS or GIF format. Metadata files Some documentation might have text or HTML files that contain management or history information about the documentation. ZIP files in standard Info-ZIP format Document source files are compressed for easy download. ZIP files can be unpacked by any compatible compressor-archiver utility, such as UnZip, WinZip*, and MacZip. For information, see the Info-ZIP Web site (http://www.info-zip.org/).

C R E A T I NG N E W D O C U M E NT S O R G RA PHI CS
1 Prepare the document or graphic using your preferred application. For guidelines, see Using Content and Style Conventions on page 6. 2 Coordinate a technical review from an SME and incorporate the feedback. For guidelines, see Ensuring the Technical Accuracy of Your Documentation on page 6. 3 Export your files to the approved exchange formats. For information, see Understanding the Documentation Source Files on page 4. 4 When you are done, zip the source files into one file. You are ready to upload the source files to the Novell Forge site. Continue with Submitting Documentation on page 6.

M O D I F Y I N G E XIS TI NG D O C U M E N T S O R G RAP HIC S

1 Download the source files for the document you have agreed to modify. 2 Using an appropriate application, open the file you want to modify. For an explanation of different file types, see Understanding the Documentation Source Files on page 4. 3 Make your changes, then save the file. For guidelines, see Using Content and Style Conventions on page 6.

4 Create a new entry in the Revision History section of the document, detailing the sections you modified and the exact changes you made. 5 Coordinate a technical review of your changes and additions by the SME responsible for the feature or API you are documenting. Repeat Step 2 through Step 4, as needed. 6 Export your files to the approved exchange format for documentation source files. 7 When you are done, compress the modified source files into a single ZIP file. You are ready to upload the modified files back to the Novell Forge site. Continue with Section , Submitting Documentation, on page 6.

U SI NG C O N T E N T A N D S T Y L E C O N V E N TI O N S
In general, all documentation contributions should conform to industry best practices for technical communication. Before you create or modify a product document, developer document, or graphic for your project, study similar documents and graphics on the Novell Forge site. Become familiar with conventions in document content, structure, and voice. For information about Novell style conventions, see the following: Documentation Style Quick Start (http://www.novell.com/documentation/osauthoring/ index.html) Documentation Graphics Style Quick Start (http://www.novell.com/documentation/ osauthoring/index.html) Documentation Localization Quick Start (http://www.novell.com/documentation/osauthoring/ index.html)

E NS UR IN G T H E T ECHNI CA L A C CU RA CY O F Y OUR D O C UM E NT A T IO N
The technical accuracy of documentation you contribute is your responsibility. There is no planned technical review after you submit it for final edit and publication. As you would in your regular development environment, use the product and discuss it with subject matter experts (SMEs) to collect the information you need. Ask SMEs to review your document and provide technical feedback as you develop it and before its final submission to the project on Novell Forge. Locate the SME for your product area in the project Members list. The Member's information usually includes a personal e-mail address. You can also contact the SME through the Project-Dev mailing list.

S UB M IT T IN G D O C UME NT A T IO N
After you create or modify material for your project, submit it to the documentation project's editors for final editing and publication. IMPORTANT: Novell reserves the right to refuse any submission or to modify, edit, or reformat the document or graphic. By submitting documentation to a project on Novell Forge, you agree to

assign to Novell any copyright claims for your work. Significant contributions are attributed in the Contributors section. To reserve your copyrights, you can host your original documentation on your own Web site and post a link to it on Novell Forge. Your independent distribution of any publication based on Novell documentation must comply with legal notices in the Novell document. 1 Log in to your Novell Login account. 2 Go to your project's Docs page. 3 Click Submit New Documentation. 4 Provide the following information: Document Title: A relevant title that uniquely identifies the document from among the many choices available on the Docs page. For example, include a version number or publication date (such as YYMMDD). Description: A brief description of the document or file contents. The description appears below the document title on the Docs page. Location: The path to the document you want to submit. Do one of the following: URL: Type the HTTP or FTP address where your document resides. If you use FTP, the site must accept anonymous login. Documentation File: To upload the file to the Novell Forge project site, type the path to the file, including the filename, on your workstation. You can also click Browse to locate the document. Group that Your Document Belongs In: From the drop-down list, select the correct group for your document. For example, select Developer, Product, or Related Resources. 5 Click Submit. A Thank You page displays to confirm your submission. 6 Click Back to return to the Docs page. An assigned Documentation Editor at Novell manages the publication of your documentation. The editor typically acknowledges your submission within five business days. The editor schedules a substantive edit for your document, depending on the availability of Novell documentation resources and project milestones, and notifies you of the schedule. The editor might return the documentation to you if major revisions are necessary. If revisions are required, submit the updated documentation source files when you are done. When the documentation is published, the editor announces its release on your project's site.

P R O V ID IN G F E E D B A C K F O R E XIS TI NG D O CU M E N T A T IO N
Novell hosts documentation for Novell Forge projects on the Novell Documentation Web Site (http:/ /www.novell.com/documentation). See your projects documentation links to access the Documentation pages for your project.

To report problems in and provide constructive feedback for existing documentation at any time, do one or more of the following: For online documentation, use the User Comment feature at the bottom of the Web page. On the project's Novell Forge site, use the Bug Tracking feature (or whatever method the project prefers) to submit a documentation defect. Make sure to explain the problem and the desired solution. Use the Novell Bugzilla Database (http://bugzilla.novell.com) to report the documentation defect. In the Project-Dev mailing list, send an e-mail that includes a description of the defect and a suggested resolution, if known.

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