Open Source Documentation Authoring Quick Start
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. As with any project, documentation is essential to help users understand how to use the product effectively and securely. Our goal is to help open source projects develop and provide quality documentation to the communities that the project serves.
We invite the project community members to contribute to the documentation development for the products they create. You can use the tips in this Authoring Quick Start to learn how to contribute documentation for open source projects that are sponsored by Novell.
1.0 What Is a Documentation Project?
A documentation project provides the framework for developing, publishing, and maintaining the product and developer documentation for the software deliverables created by an open source project’s developers. It is a community effort. Documentation contributors 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.
We publish the documentation for stable releases in HTML and PDF format on the Novell Documentation website, where it can be updated regularly as part of Novell’s ongoing documentation development. We link to the documentation’s web page from the project site.
2.0 How to Contribute
Your participation and contributions are welcome. You can contribute through user comments, project communities and email, or more formal methods.
2.1 User Comments
Our documentation websites offer an interactive Comments option at the bottom of every HTML page. You can comment at any time on existing books to contribute content, report problems, provide constructive feedback, or request enhancements. Comments are automatically sent directly to the lead writer for the project. The writer will contact you to get clarification, gather extended input, and notify you when the manual has been updated and republished.
2.2 Project Communities and Email
Every open source project has a forum or mailing list for the community where features and issues are discussed. Novell writers monitor them to collect material for future documentation releases. For example, we might use solutions, workarounds, best practices, tips and tricks, or frequently asked questions to improve and enhance the product’s manuals and help. You can use these communities to contribute formally or informally to the documentation.
2.3 Novell Bugzilla (Request New Topics or Manuals)
Novell sponsored open source projects typically capture bug reports and enhancements requests in Novell Bugzilla. You can file a bug report to request coverage for new features or to request new types of manuals.
To submit and view bugs, you must create a login account on Novell.com. Registration is free. Your login account is designed to allow you to use a single set of authentication credentials to access all of the secure applications or databases on NetIQ, Novell, and SUSE to which you have entitlement rights.
2.4 Contribute Sections, Chapters, or Manuals
To contribute sections, chapters, or manuals to the documentation set, please contact us via user comments or the project communities. We can provide source files or examples to get you started. You can contribute your work in XML with formatting that is consistent with our in-house documentation development process, or you can use standard word processing formats like ODT or DOC.
Our manuals are written in DocSys XML, our in-house version of DocBook. We develop and generate books with our DocSys tools for Adobe FrameMaker. Our files are stored in a source-control repository. This development and build environment does not have an open-source counterpart that you can access directly, nor do we provide the related software to you to develope documentation. However, you can receive master files and contribute content in our modified DocSys XML format, using your preferred tools to create the documents.
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
-
Localize existing documentation
3.0 Volunteering for Documentation Tasks
The documentation lead for an open source project typically maintains a list of the major tasks that need to be done. For external project sites, the list is maintained on the project’s Documentation page so that new contributors see what tasks need to be done and can volunteer for the effort. 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. For any or the documentation projects, you can post a user comment for the online manual to volunteer, and the assigned Novell writer will contact you via email to learn about your areas of interest and your availability.
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.
Subscribe to the project’s mailing list to learn more about the project and its key players. You can read current and archived messages online, or you can subscribe to the list to have new messages delivered to your email account.
To begin a dialog about contributing content to the project’s documentation, you can post a user comment from any page of the online manual, send an email to the mailing list, or post a message in the community forum. A documentation project editor typically replies via email within five business days to follow up and make further arrangements if needed.
4.0 Documentation Source XML Files
After you accept a documentation assignment, you can request a copy of the XML and graphics source files for your project. If you are creating a new document, you can request the XML files for a similar document to familiarize yourself with the style and format.
Source files can include the following file types:
-
XML files in DocBook XML standard markup format
Novell applies its documentation style sheet to the XML files to generate viewable and downloadable HTML and PDF files.
For general information about DocBook tags, see the DocBook.org website or the Organization for the Advancement of Structured Information Standards (OASIS) DocBook Technical Committee website.
-
PNG files are used for screen shots and for illustrations presented online.
-
EPS files for illustrations included in the manual. The graphic must also exported in PNG format for online viewing.
-
Metadata files
Some documentation might have text 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.org website.
5.0 Style Guidelines
In general, all 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 Documentation website. Become familiar with conventions in document content, structure, and voice.
Use your preferred applications to prepare the document or graphics.
5.1 Graphics Style Conventions
Novell requires illustrations to use EPS and PNG format. Screen shots use PNG format. For information about style and format requirements for illustrations and screen shots, see the Open Source Documentation Graphics Style Quick Start
5.2 Documentation Style Conventions
For information about Novell style conventions for manuals, see the Open Source Documentation Style Quick Start.
5.3 Localization Conventions
For information about localization conventions, see the Open Source Documentation Localization Quick Start.
5.4 Technical Accuracy
You are responsible for the technical accuracy of documents that you contribute. There is no planned technical review after you submit content for final editing and publication.
You should discuss the product with its subject-matter experts to learn about its features and expected usage. It is also expected that you will use the product and collect the information you need about tasks to be performed. Ask subject-matter experts to review your document and provide technical feedback as you develop it and before its final submission to the project.
You can get the subject-matter expert’s contact information through project mailing list.
6.0 Submitting Documentation
IMPORTANT:Novell reserves the right to refuse any submission or to modify, edit, or reformat the document or graphic. By submitting documentation to an open source project, 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 website and post a link to it from the project website or forums. Your independent distribution of any publication based on Novell documentation must comply with legal notices in the Novell document.
After you create or modify material for your project, zip the source files into a single file. File a bug in Novell Bugzilla and attach the zipped file. The file will be retrieved by the project’s lead writer for final editing and publication.
-
Document Title: Specify a relevant title that uniquely identifies the material. If it is a section for a larger document, ensure that you also provide the title of its parent document.
-
Description: Provide brief description of the document or file contents.
-
Component: From the drop-down list, select or select the related component.
-
Zipped file: Scroll down to the bottom of the form, select , then follow the on-screen instructions to attache the Zipped file.
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.
7.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.