AGDP Manifesto

With the launch of the new accessgrid.org portal, the AGDP has ceased to operate as a separate entity.

Since the AGDP documents are still a valuable resource, we plan to leave the site essentially intact for the time being. Most of the documents on this site carry open-source licenses, therefore making anyone free to update them, modify them, and post on the portal or anywhere else they find appropriate, provided that the license/copyright policies of that site aren't in conflict. Some of these documents have already been added to the portal. (A prominent exception is the AG Training Project tutorials; these tutorials will remain available in their WebCT form, and I have linked to them from the new accessgrid.org portal; however, they are not licensed for free re-distribution.) AGDP authors and contributors are encouraged to contribute materials to the new portal.

1. Overview

The Access Grid Documentation Project (AGDP) develops free, high-quality documentation for the Access Grid (AG). We aim to establish a set of documentation that will be easy to use and search. This includes HOWTO documents, FAQs, tip sheets, tutorials, and guides.

The AGDP owes a great debt of gratitude to the Linux Documentation Project (LDP), on whose model the AGDP has been created, and on whose manifesto our own manifesto is based.

The AGDP's goal is to create the canonical set of AG documentation. This documentation can be viewed online, downloaded, included on CD distributions, and printed in books. If you are interested in re-publishing any of the AGDP works, see the section "Publishing AGDP Documents" below.

The AGDP is essentially a loose team of volunteers with minimal central organization. Anyone who would like to help is welcome to join in this effort. We feel that working together informally and discussing projects on our mailing lists is the best way to go. When we disagree on things, we try to reason with each other until we reach an informed consensus.

2. Current projects and getting involved

If you would like to write a document for the AGDP, please see our "Wish List and Works in Progress" page. If you have a specific topic already in mind, please check to see if one is already in progress on that topic; if so, you may wish to get in touch with the contact person for that document and offer to help. Otherwise, the wish list can help you choose a topic. Before getting started on your document, we strongly suggest that you read the AGDP Author's Guide.

Other tasks include converting documents into DocBook format, helping to improve our website, and assisting in the day-to-day management of the AGDP. If you are interested in any project other than developing documentation, please send mail to agdp-coordinate@accessgrid.org.

3. Documentation conventions

Types of Documents

AGDP documents are organized into several categories:

  • HOWTOs are detailed "how to" documents on specific subjects. For example, a HOWTO on Distributed PowerPoint would describe all the steps necessary for installing and running this piece of software. HOWTOs also generally focus on a very specific topic.
  • Tip Sheets are brief documents with, well, tips on a given topic.
  • FAQs are lists of frequently asked questions, with their answers.
  • Guides have a broader focus, and are generally longer documents. Although they sometimes include step-by-step instructions on specific topics, they provide a more comprehensive overview of the subject at hand. For example, a Guide on developing a training course to be held over the AG might include sections on selecting appropriate supporting technologies, training speakers on effective communications over the AG, and coordinating local logistics among multiple participating sites.
  • AGiB Tutorials are in-depth web-based training materials developed specifically t support AG software releases.

The AGDP Authors' Guide provides some suggestions regarding how to get started writing either of these types of documents, as well as templates for the file formats described below and specific conventions on how to format text for different purposes (ie, how to indicate a command and related options). The Authors' Guide also includes a brief overview of the review process, so you'll know what to expect when you submit your document to us for possible publication.

File Formats for Documents

If you are submitting a document to the AGDP which you have not submitted before, you may send it to us in any commonly available file format (for example, Word, HTML, or RTF). After it is approved for posting to the AGDP, a member of the AGDP team will convert it to SGML DocBook. Using the DocBook code, this volunteer will then render your document into other file formats for posting on the AGDP (including, but not necessarily limited to, HTML and PDF).

We do encourage you to submit your documents in DocBook SGML when possible. The AGDP Authors Guide has some tips on getting started with DocBook, as well as an AGDP template.

4. Licensing

All documents published on the AGDP must be licensed in such a way that they can be freely redistributed, in both electronic and print forms. We also strongly suggest that document licenses allow for the creation of derivatives.

Authors may write their own license terms, or use a previously prepared license.

The copyright for each document should be in the name of the principal authors. "The Access Grid Documentation Project" isn't a formal entity and thus can't be used as a copyright owner.

Authors are responsible for determining what responsibilities, if any, they have to their organization's funding sources when writing copyright and license notices.

The AGDP supports AG Toolkit software releases whenever possible. As the AG Tookit distributions require a BSD-style license, AGDP authors who hope to have their work included in such software distributions should use the following license:

Copyright c 2001-2002 by [copyright holder]. Permission is 
hereby granted to use, reproduce, to redistribute copies to
others, and prepare derivative works. Any use or publication
of the material shall acknowledge the copyright of [copyright
holder] in an appropriate manner which shall include the 
legend "c [year] by [copyright holder], includes materials
developed by and/or derived from the Access Grid project 
(http://www.accessgrid.org)."

Those who prefer a GPL-style license, and understand their documentation won't be eligible for distribution with AG Toolkit software releases, may wish to use the following iinstead:

Copyright (c) [year] by [copyright holder]


Please freely copy and distribute (sell or give away)
this document in any format. It's requested that corrections
and/or comments be forwarded to the document maintainer. You
may create a derivative work and distribute it provided that
you:


1. Send your derivative work (in the most suitable format,
such as DocBook) to the AGDP (Access Grid Documentation
Project) or the like for posting on the Internet. If not
the AGDP, then let the AGDP know where it is available.

2. License the derivative work with this same license or
use GPL. Include a copyright notice and at least a
pointer to the license used.

3. Give due credit to previous authors and major
contributors. If you're considering making a derived
work other than a translation, it's requested that you
discuss your plans with the current maintainer.
If neither of the boilerplate licenses above suits you, we suggest you visit The Open Source Initiative's web page on licenses to find one that does. As long as the document is freely redistributible in all media, it will meet the AGDP's licensing criteria.

5. Publishing AGDP documents

If you're a publishing company interested in distributing any of the AGDP documents, read on.

Anyone is allowed to publish and distribute verbatim copies of most of the Access Grid Documentation Project documents. You don't need our explicit permission for this. (Because there are exceptions to this general rule, please check the copyright notice and any applicable license on any AGDP work before you modify and/or redistribute.) However, if you would like to distribute a translation or derivative work based on any of the AGDP documents, you may need to obtain permission from the author, in writing, before doing so, if the license requires that.

You may, of course, sell the AGDP documents for profit. We encourage you to do so. Keep in mind, however, that because the AGDP documents are freely distributable, anyone may make copies and distribute them. Thus the parts of a book that may be freely copied should be separated (and identified) in such a manner as to facilitate copying them without infringing on the copyright of other material.

We do not require you to pay royalties from any profit earned by selling AGDP documents. However, we would like to suggest that if you do sell AGDP documents for profit, that you either offer the author royalties, or donate a portion of your earnings to the author, the AGDP as a whole, or to the Access Grid development community. You may also wish to send one or more free copies of the AGDP documents that you are distributing to the authors. Your show of support for the AGDP and the Access Grid community will be very much appreciated.

We would like to be informed of any plans to publish or distribute AGDP documents, just so we know how they're becoming available. If you are publishing or planning to publish any AGDP documents, please send mail to agdp-coordinate@accessgrid.org. It's nice to know who's doing what.

We encourage people distributing software intended for use over the Access Grid to distribute AGDP documents on CDs or websites along with their software. The AGDP documents are intended for use as "official" Access Grid documentation, and we are glad to see distributors bundling the AGDP documents with the software.

This document is maintained by Jennifer Teig von Hoffman, jtvh@bu.edu. We welcome your questions and comments.