Looks great Michelle. I think we're finally off to a good start. I'm greatful to you for taking leadership and driving this effort forward. Great things are ahead!
benr. Michelle Olson wrote: >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. >> >> >> >> >> >>------------------------------------------------------------------------ >> >>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 >>
