Hi all,
I've drafted a list of procedures and steps below to help new and existing
community members understand how to collaborate on documentation for
OpenSolaris. This could be added to the How To Participate page, or could be
separate page or doc.
This is a work in progress (and it presumes that a Review page exists--I think
we could use one, what do you think?) I'm sure I haven't covered everything,
but this a start at least.
I'd really appreciate your thoughts on this content, with focus on errors,
omissions, items that are not clear, or anything else that needs
clarification. Let me know what you think.
Thanks,
Michelle
Instructions for Open Information Development
-------------------------------------------------------------------
The purpose of this document is to describe the instructions for collaborative
documentation development in the OpenSolaris project.
Collaborative Documentation Development Tasks
-------------------------------------------------------------------
Write a new document
Request to view a document
Request a change to a document
Send review feedback for a document
Send URL for a requested or new document
Respond to a documentation change request
Communicate changes and contributions to a document
License the source for a document
Add text to an existing document
File and fix a documentation bug or RFE
Post a document
Post source for a document
Submit a patch to an open source document
Introduce yourself
Instructions
-----------------------------------------------------------------
1-Write a new document:
1a-Write content in any format (text, HTML, PDF, etc.) and send it to
docs-discuss at opensolaris.org.
1b-Write structured content using XML:
Note: Processing of the XML is not yet supported with tools on the
opensolaris.org
web site, so the processing is your responsibility to complete until we get the
tools ready sometime before end of July 2006.
1-Download and license the source for a document you want to use as a
template using the instructions here:
http://dlc.sun.com/osol/docs
2-Load the DocBook DTD into your favorite editor using the
instructions here:
http://opensolaris.org/os/community/documentation/templates
3-Open the template file in your editor, edit the content keeping in
mind
the published documentation style guidelines and terminology
guidelines, and save the file.
4-Email the changed file to docs-discuss at opensolaris.org with a
brief description of your changes and the headings where
the new content appears.
2-Request to view a document: Send email to docs-discuss at opensolaris.org
3-Request a change to a document: File a doc bug at http://bugs.opensolaris.org
and specify Doc as the subcategory.
4-Send review feedback for a document: Reply to doc postings at
http://opensolaris.org/os/community/documentation/discussions
5-Send URL for a requested or new document: Monitor an opensolaris forum alias,
and respond to requests for documentation or cross-post them to the
docs-discuss
alias if you don't know the location of a document.
6-Respond to a documentation change request: Review bugs that have the
'opensolaris' keyword and check to see if the submitter in field 6 answered
Yes/No
to the 'Submitter wants to work on bug' field. If not, proceed to address the
change according to existing processes. If they answered Yes, contact a doc
community leader to get started with working in the open.
7-Communicate changes and contributions: Post changed documents to docs-discuss
at opensolaris.org and cc: the bug submitter or contributor with a brief
description of the change and under what heading it appears in the updated
review copy. Feel free to also provide any addtional review details that might
be appropriate.
8-License the source for a document: Go to http://dlc.sun.com/osol/docs to
download source and accept the terms of the license.
9-Add content to an existing document: Use 4 above if the document is not yet
available as open source. Use 8 above if the document is available as open
source and you want to collaborate on the XML.
10-File and help to fix a documentation bug or RFE: File a doc bug at
http://bugs.opensolaris.org and specify Doc as the subcategory. Then, answer
yes to the 'Submitter wants to work on bug' field and a community leader will
contact you to request a contributor agreement and get you in touch with the
original author.
11-Post a document: If you are a doc community leader, post documents to the
Files page and create a link from the appropriate Review page, Big Doc List, or
Doc Downloads page. If you are a doc community member who is not a leader, send
email to docs-discuss at opensolaris.org to request that a document be posted
or attach the file to request a review.
12-Post the source for a document: Source that is published in the Doc
Consolidation must adhere to the Documentation Style Guide for OpenSolaris and
the terminology guidelines provided in the Sun Global Glossary. The source must
also be licensed according to appropriate guidelines outlined at
http://opensolaris.org/os/community/documentation/license and be provided in an
acceptable format for collaboration (currently DocBook5 XML for manuals, TBD
for man pages). Other source files may be uploaded to the /tmp directory on the
docs community site, just request a leader to do so by sending mail to
docs-discuss at opensolaris.org.
13-Submit a patch to an open source document: Use 8 above to download and
license content, then use 1b above to edit the content and request review and
incorporation. (This process will improve with time, firstly, by having a way
to transform the XML into HTML for reviews, and secondly, by having a source
management system set up for true collaborative development.)
14-Introduce yourself: Send us your ideas for instructions, guidelines, and doc
collaboration by posting a message to docs-discuss at opensolaris.org.
This message posted from opensolaris.org
