I'm starting a new thread for cleanliness sake; for prior discussion
leading to this please see the "Directions and Objectives" thread.
Rather than a variety of guideline documents, perhaps its best to have
one. How about:
"OpenSolaris Documentation Contribution Guidelines: Licensing,
Attribution, and Submission"
Okey, a little long winded, but we're authors, thats what we are good
at. The document should cover the following specific topics:
1) Contributing to OpenSolaris Documentation: An outline of how an
interested author can:
a. Gain access to documentation in "source" form (XML/(La)TeX/(n)roff)
b. Propose major changes to an existing document or creation of an
entirely new document
c. Stay aware of what is happening within the documentation community
and ensure they aren't duplicating other ongoing/existing work; how to
stay coordinated. (RFE lists/bug tracks/etc)
2) Documentation Contribution Model: Details reguarding the following
topics:
a. Outline of the various types of documenation, such as:
- Official Manuals (docs.sun.com)
- Official Supplimental Documentation (BluePrints class)
- Articles (Trade Rag class)
- Man Pages
- Java Help
- Informal Supplimental Documentation (SunSolve InfoDoc's class,
highly focused on a single aspect of a single topic)
b. Licensing Model for various classes of documentation. CDDL? CC?
Artistic License?
c. Attribution models based on various licenses (attribution in
source? attribution on single doc-wide "Authors & Contributers" page?
attribution per section/chapter?)
d. How OpenSolaris Documenation Community docs (will eventually) fit
in with Sun Microsystem official documentation. (ie: Answer the "Will
my addition go in the release docs!?!" questions.)
e. Contribution methodology (the "how" of this thing. Can you just
sent an XML diff? Can you just submit a finished work? Can you .... so
on and so forth. How does start working once they get involved.)
3) Documentation Style Guide: Technical information reguarding
typesetting, guidelines for layout, etc, such as:
a. Official typesetting systems based on the various classes of
documentation. (Solbook, JavaDoc, roff, etc)
b. Output methods and types based on the variosu classes of docs (PDF,
HTML, HTML Chunk, etc)
c. Formatting and organization (chapter layout such as intro, concept,
task, concept, task, etc; ideas/concepts per section; sections per
chapter, chapters per book, pp per section, etc.)
d. Front/Back matter issues for various types of documentation (TUO,
Disclammers, copyright notice, license notice, etc.)
I'll leave it at that for now. The idea here is that a good set of
guidelines should give me, as an author, the information that I need to
start producing documentation the looks, feels, and jives with existing
documentation without having to ever disturb Sun TechPubs or require a
sponsor.
These things above obviously hinge a plenty of other decisions; such as:
- Will Sun release Solbook and the associated stylesheets or are we too
dumb to figure it out?
- Will we have a source repository for storing and sharing
documentation? (Subversion/CVS)
- Will existing docs be released in source form?
- Where will we host documenation?
- What licenses are we going to use? What we going to permit
contributers to use?
etc, etc, etc.
Ideas? Feedback? Am I on the right track here or are we not ready to
work toward this sort of doc yet? I realize that a lot needs to happen
first to answer some of these questions before we form a guideline, but
I think we need to get cracking on those problems sooner rather than latter.
benr.
