Author: robweir
Date: Fri Feb 22 18:40:35 2013
New Revision: 1449164
URL: http://svn.apache.org/r1449164
Log:
initial draft of intro-doc.mdtext
Added:
openoffice/site/trunk/content/orientation/intro-doc.mdtext
Modified:
openoffice/site/trunk/content/orientation/index.mdtext
openoffice/site/trunk/content/orientation/intro-development.mdtext
Modified: openoffice/site/trunk/content/orientation/index.mdtext
URL:
http://svn.apache.org/viewvc/openoffice/site/trunk/content/orientation/index.mdtext?rev=1449164&r1=1449163&r2=1449164&view=diff
==============================================================================
--- openoffice/site/trunk/content/orientation/index.mdtext (original)
+++ openoffice/site/trunk/content/orientation/index.mdtext Fri Feb 22 18:40:35
2013
@@ -55,6 +55,7 @@ The Orientation Modules for the various
* [Introduction to QA](intro-qa.html)
* [Introduction to
Localization](http://openoffice.apache.org/translate.html) (How to Help
Translate OpenOffice)
* [Introduction to Marketing](intro-marketing.html)
+ * [Introduction to Documentation](intro-doc.html)
* Introduction to Website Content Authoring
* Level 4: Intermediate Specialized Areas
Modified: openoffice/site/trunk/content/orientation/intro-development.mdtext
URL:
http://svn.apache.org/viewvc/openoffice/site/trunk/content/orientation/intro-development.mdtext?rev=1449164&r1=1449163&r2=1449164&view=diff
==============================================================================
--- openoffice/site/trunk/content/orientation/intro-development.mdtext
(original)
+++ openoffice/site/trunk/content/orientation/intro-development.mdtext Fri Feb
22 18:40:35 2013
@@ -121,5 +121,5 @@ a lot of information, some of it up-to-d
## Module Completion
Once you have completed this module, go to our our [Directory of
Volunteers](https://cwiki.apache.org/confluence/display/OOOUSERS/Directory+of+Volunteers)
wiki page and add or update
-your information. Congratulations! Please send a note to
[[email protected]](mailto:[email protected]?subject=Completed
Introduction to Development) so we know.
+your information. Congratulations! Please send a note to
[[email protected]](mailto:[email protected]?subject=Completed
Introduction to Development) so we know.
Added: openoffice/site/trunk/content/orientation/intro-doc.mdtext
URL:
http://svn.apache.org/viewvc/openoffice/site/trunk/content/orientation/intro-doc.mdtext?rev=1449164&view=auto
==============================================================================
--- openoffice/site/trunk/content/orientation/intro-doc.mdtext (added)
+++ openoffice/site/trunk/content/orientation/intro-doc.mdtext Fri Feb 22
18:40:35 2013
@@ -0,0 +1,105 @@
+Title: Introduction to Documentation
+Notice: Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+ .
+ http://www.apache.org/licenses/LICENSE-2.0
+ .
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+##Introduction
+
+In this orientation module you will learn how to get started in the OpenOffice
Documentation Team
+
+To complete this module, read through the material on this page, including the
linked references. There will also
+be some start-up tasks for you to perform, such as signing up for an account
in our wiki.
+
+Your first task is to subscribe to our Documentation mailing list. You can
subscribe by sending an email to
+[[email protected]](mailto:[email protected]).
+
+Then you can introduce yourself by [sending an email to the
list](mailto:[email protected]?subject=New Doc Volunteer).
+We'd love to hear who you are, where you are from, what your background is,
etc. Also as you work through the
+items on this page, if you have questions or problems, please feel free to ask
for help by sending a note to
+this same list.
+
+Note: In parallel with the Doc-specific items on this page, you may want to
also review the [Level 1 and Level 2 Orientation
Modules](http://openoffice.apache.org/orientation/index.html). They have
useful background information on The Apache Way, mailing list etiquette,
decision making in the
+project, etc. A quick review is a good idea, especially if you are new to
working in Apache-style open source projects.
+
+Now with the introductions out of the way, let's get started!
+
+##The Big Picture
+
+As a popular end-user facing product, Apache OpenOffice is used by millions of
people around the world, with a wide range of skills and backgrounds. Some
have been using OpenOffice for
+a decade. Others are just moving over from Microsoft Office. Some are very
familiar with computers and their operating systems. Others may be using a
computer for the first time. Some
+are doing just basic editing. Others are "power users" and are creating
complex applications built on top of OpenOffice.
+
+When users have a question, when they get stuck, there are a wide range of
options for them:
+
+ - They might ask a friend for help
+ - They might search Google for help
+ - They might press F1 in the application and look for help
+ - They might post a question to our [community support
forum](http://forum.openoffice.org)
+ - They might go to the [OpenOffice.org website](http://www.openoffice.org)
and look for a solution there
+
+The documentation we write aids both the end-users as well as those who
support the end users. We aim to provide authorative, up-to-date material for
Apache OpenOffice, and to aid
+users of all skill levels. If we do our tasks well, users are more satisfied
and more productive.
+
+##Varieties of Documentation
+
+We maintain documentation in a variety of forms:
+
+ - Built-in help files that are included in the product installs. These are
context-sensitive help files that you get when you press "F1" in an OpenOffice
application.
+ - User Guides that are available on the website. These include a mixture of
overview and task-specific topics.
+ - Special topics, such as migration guides, scripting cookbooks, etc.
+
+##Goals and Constraints
+
+In our documentation work we need to be aware of the following goals and
constraints:
+
+ - Only around 1/3 of OpenOffice users speak English as their native
language. This is true also of the volunteers working on documentation. So in
our list conversations, and in our
+ documentation, we should aim for good, simple English prose, avoiding
regional idioms and jargon. By convention we're adopting U.S. English spelling
for the documentation.
+ So we should plan for the documentation we write to be translated at some
point.
+ - We should also write the documentation so it can be translated into other
languages. This means we need to be careful about how we mix text and graphics
together in any diagrams.
+ - We use the [Apache License
2.0](http://www.apache.org/licenses/LICENSE-2.0.html) for all project
deliverables. This "permissive" open source license ensures that everyone has
the
+ ability to adapt and reuse the documentation that we create. But it also
means that we need to be careful about what other 3rd party material we use in
our documentation. Until you
+ are familiar with the Apache rules for using 3rd party material into an
Apache product, you should start a discussion on the mailing list for any 3rd
party material you want to reuse.
+ This includes material from the legacy OpenOffice.org project as well, since
some of that was under a different license.
+ - We're aiming to provide as much content as possible in the form of MWiki
pages. These are easy for users to access, from any device. Also, since they
are indexed by search engines
+ they will be easy to find for the users who like to resolve issues by
searching Google for solutions.
+
+
+##Volunteers are Welcome
+
+We're looking for volunteers with technical writing experience, a good working
knowledge of OpenOffice, or ideally both. The ability to collaborate with
others in written English
+on the mailing list is required, but you just need to be understandable. For
the actual writing, we have editor volunteers who will review and edit the
rough drafts to fix any
+language errors. So you don't need to have native-level English skills.
+
+For some specialized areas skills in graphic design and programming are also
useful.
+
+Volunteers on the Documentation Team work on a variety of tasks, including:
+
+ - Authoring draft documentation on a specific area of the OpenOffice product.
+ - Reviewing draft documentation for technical correctness, e.g., repeating
the steps described in a task and verifying that they are complete and no steps
are missing.
+ - Editing draft documentation for clarity and style.
+ - Preparing screenshots, diagrams and artwork for covers.
+ - Developing tools and scripts to aid in repetivive tasks, such as document
format conversions.
+
+##Getting Started
+
+The Documentation Team is the easiest one to get started with. Just [send an
email to the mailing list](mailto:[email protected]?subject=New Doc
Volunteer) and introduce
+yourself. We can then bring you up to speed on what we're currently working
on.
+
+## Module Completion
+
+Once you have completed this module, go to our our [Directory of
Volunteers](https://cwiki.apache.org/confluence/display/OOOUSERS/Directory+of+Volunteers)
wiki page and add or update
+your information. Congratulations! Please send a note to
[[email protected]](mailto:[email protected]?subject=Completed
Introduction to Documentation) so we know.
+
