Hi Ben,
Thanks for this response, I really appreciate your thoughts on the
many sets of guidelines I proposed in the last thread! I've been
meaning to summarize our discussion at the SVOSUG in my blog all week
and haven't had the time, so I'm glad you 'made' some time to write
this.
In summary, I think you are dead-on with this list! I mentioned that
an assessment/adjustment activity was underway with respect to the doc
roadmap in P-team this week, so I will bring your thoughts and any
others that come in to that team on Monday to get more feedback. Below
is summary list of what I think should be adjusted in the roadmap,
based on my first month on the project.
As status report, I've made the most progress on your #3 below this
week (style guide), see the outline attached. #3 must come first, IMO,
because we can't tell folks how to contribute without aiding them in
the writing of a piece of technical information.
Your 1b and 1c are 'technically' covered at this time by the
sponsorship model and docs-discuss alias. But, I think this is part of
the 'roadmap adjustment' that needs to be addressed. That is, the
sponsorship model should be augmented with a straight forward
contribution/collaboration model. In addition, information about doc
bugs and bug management needs to be added. 1a (dowloadable doc src) is
crucial and definitely needs to be added to our roadmap in an earlier
phase, but this piece is most complex and must be worked through a
number of channels, so I see it as a longer-term item with smaller
steps in between.
I think your #2 fits into #1 and #3. Check out the outline for the
style guide to see where I'm guessing 2a, 2b, and 2c fit in. Then 2d
and 2e should go with the 'How To Submit Docs' guidelines.
In summary, I think we have immediate need for 2 guideline documents:
1-OpenSolaris Style Guidelines (see attached for alpha TOC draft)
2-How To Contribute OpenSolaris Docs (coming soon)
Then, we have items to propose for the roadmap adjustment, in no
particular order:
1-indicate progress on style guide
2-indicate progress on man page due diligence
3-assess and indicate progress on global glossary work
4-add 'downloadable src' detail to phase2
5-add contribution model to phase1
6-add doc index for opensolaris site to phase1
7-add SGML templates published to phase2
8-add doc community page beta revision posted to phase1
9-add bug tracking and coordination info to beta doc community page
10-add metablogging/aggregate blog feature to phase2
11-add content submission form to phase1
12-add auto-index feature to opensolaris.org 'add attachment' form
Others? I will detail these 12 items on Monday, so that everyone can
understand them and feedback, but I wanted to duplicate the list for
the docs-discuss group so you'll have a sense of my ideas for the
roadmap updates before the p-team.
Keep 'em coming!
Thanks again,
Michelle
>Date: Fri, 28 Oct 2005 02:00:52 -0700
>From: Ben Rockwood <benr at cuddletech.com>
>User-Agent: Mozilla Thunderbird 1.0.6 (X11/20050720)
>X-Accept-Language: en-us, en
>MIME-Version: 1.0
>To: Michelle Olson <mo137222 at jurassic.sfbay.sun.com>
>CC: docs-discuss at opensolaris.org
>Subject: Guidelines and Forward looking projects proposal
>Content-Transfer-Encoding: 7bit
>
>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.
>
>
>
-------------- next part --------------
Proposal: OpenSolaris Style Guide
Table of Contents
__________________________________
Preface
About This Guide
How This Book Is Organized
Who Should Read This Guide
Associated Documentation
Related Documentation
Reference Sources
1. Constructing Text
Headings
Lists
Tables
Code Examples
Man Page References
Error Messages
Cross-References
Notes, Cautions, and Tips
Illustrations
2. Technical Documentation Concepts
Stylistic Principles
Online Writing Style
Write for the Reader
Avoid Style That Could Offend the Reader
Common Writing Problems to Avoid
Structure
Types of Software Manuals
Other Product Documents
4. Writing for an International Audience
Guidelines for Writing for Translation
5. Checking and Reviewing Your Document
Reviews
Checks You Can Do Yourself
6. Indexing Your Documentation
Creating an Index
Refining and Checking an Index
7. Glossary Guidelines
Glossary Content
Writing Good Glossary Entries
8. Legal Guidelines
Legal Requirements Checklist
OpenSolaris License Agreement CDDL
Copyrights and Trademark Attributions
9. Writing Alternative Text for Nontext Elements
General Guidelines for Writing Alternative Text
Writing About Nontext Elements
10. Writing for the Solbook DTD
General Guidelines for Writing to the Solbook DTD
A. General Word Usage
B. OSSG Contributors
