openoffice-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From build...@apache.org
Subject svn commit: r1039997 - in /websites/staging/openoffice/trunk/content: ./ orientation/intro-doc.html
Date Tue, 05 Feb 2019 12:53:06 GMT
Author: buildbot
Date: Tue Feb  5 12:53:06 2019
New Revision: 1039997

Log:
Staging update by buildbot for openoffice

Modified:
    websites/staging/openoffice/trunk/content/   (props changed)
    websites/staging/openoffice/trunk/content/orientation/intro-doc.html

Propchange: websites/staging/openoffice/trunk/content/
------------------------------------------------------------------------------
--- cms:source-revision (original)
+++ cms:source-revision Tue Feb  5 12:53:06 2019
@@ -1 +1 @@
-1853001
+1853002

Modified: websites/staging/openoffice/trunk/content/orientation/intro-doc.html
==============================================================================
--- websites/staging/openoffice/trunk/content/orientation/intro-doc.html (original)
+++ websites/staging/openoffice/trunk/content/orientation/intro-doc.html Tue Feb  5 12:53:06
2019
@@ -137,45 +137,41 @@ h2:hover > .headerlink, h3:hover > .head
 <h2 id="the-big-picture">The Big Picture<a class="headerlink" href="#the-big-picture"
title="Permanent link">&para;</a></h2>
 <p>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 decades. 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.</p>
 <p>When users have a question, when they get stuck, there are a wide range of options
for them:</p>
-<div class="codehilite"><pre><span class="o">-</span> <span class="n">They</span>
<span class="n">might</span> <span class="n">ask</span> <span class="n">a</span>
<span class="n">friend</span> <span class="k">for</span> <span
class="n">help</span>
-<span class="o">-</span> <span class="n">They</span> <span class="n">might</span>
<span class="n">search</span> <span class="n">Google</span> <span
class="k">for</span> <span class="n">help</span>
-<span class="o">-</span> <span class="n">They</span> <span class="n">might</span>
<span class="n">press</span> <span class="n">F1</span> <span class="n">in</span>
<span class="n">the</span> <span class="n">application</span> <span
class="n">and</span> <span class="n">look</span> <span class="k">for</span>
<span class="n">help</span>
-<span class="o">-</span> <span class="n">They</span> <span class="n">might</span>
<span class="n">post</span> <span class="n">a</span> <span class="n">question</span>
<span class="n">to</span> <span class="n">our</span> <span class="p">[</span><span
class="n">community</span> <span class="n">support</span> <span class="n">forum</span><span
class="p">](</span><span class="n">https</span><span class="p">:</span><span
class="o">//</span><span class="n">forum</span><span class="p">.</span><span
class="n">openoffice</span><span class="p">.</span><span class="n">org</span><span
class="o">/</span><span class="p">)</span>
-<span class="o">-</span> <span class="n">They</span> <span class="n">might</span>
<span class="n">go</span> <span class="n">to</span> <span class="n">the</span>
<span class="p">[</span><span class="n">OpenOffice</span><span
class="p">.</span><span class="n">org</span> <span class="n">website</span><span
class="p">](</span><span class="n">https</span><span class="p">:</span><span
class="o">//</span><span class="n">www</span><span class="p">.</span><span
class="n">openoffice</span><span class="p">.</span><span class="n">org</span><span
class="p">)</span> <span class="n">and</span> <span class="n">look</span>
<span class="k">for</span> <span class="n">a</span> <span class="n">solution</span>
<span class="n">there</span>
-</pre></div>
-
-
+<ul>
+<li>They might ask a friend for help</li>
+<li>They might search Google for help</li>
+<li>They might press F1 in the application and look for help</li>
+<li>They might post a question to our <a href="https://forum.openoffice.org/">community
support forum</a></li>
+<li>They might go to the <a href="https://www.openoffice.org">OpenOffice.org
website</a> and look for a solution there</li>
+</ul>
 <p>The documentation we write aids both the end-users as well as those who support
the end users. We aim to provide authoritative, 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.</p>
 <h2 id="varieties-of-documentation">Varieties of Documentation<a class="headerlink"
href="#varieties-of-documentation" title="Permanent link">&para;</a></h2>
 <p>We maintain documentation in a variety of forms:</p>
-<div class="codehilite"><pre><span class="o">-</span> <span class="n">Built</span><span
class="o">-</span><span class="n">in</span> <span class="n">help</span>
<span class="n">files</span> <span class="n">that</span> <span
class="n">are</span> <span class="n">included</span> <span class="n">in</span>
<span class="n">the</span> <span class="n">product</span> <span
class="n">installs</span><span class="p">.</span> <span class="n">These</span>
<span class="n">are</span> <span class="n">context</span><span
class="o">-</span><span class="n">sensitive</span> <span class="n">help</span>
<span class="n">files</span> <span class="n">that</span> <span
class="n">you</span> <span class="n">get</span> <span class="n">when</span>
<span class="n">you</span> <span class="n">press</span> &quot;<span
class="n">F1</span>&quot; <span class="n">in</span> <span class="n">an</span>
<span class="n">OpenOffice</span> <span class="n">application</span><span
class="p">.</span>
-<span class="o">-</span> <span class="n">User</span> <span class="n">Guides</span>
<span class="n">that</span> <span class="n">are</span> <span class="n">available</span>
<span class="n">on</span> <span class="n">the</span> <span class="n">website</span><span
class="p">.</span> <span class="n">These</span> <span class="n">include</span>
<span class="n">a</span> <span class="n">mixture</span> <span class="n">of</span>
<span class="n">overview</span> <span class="n">and</span> <span
class="n">task</span><span class="o">-</span><span class="n">specific</span>
<span class="n">topics</span><span class="p">.</span>
-<span class="o">-</span> <span class="n">Special</span> <span
class="n">topics</span><span class="p">,</span> <span class="n">such</span>
<span class="n">as</span> <span class="n">migration</span> <span
class="n">guides</span><span class="p">,</span> <span class="n">scripting</span>
<span class="n">cookbooks</span><span class="p">,</span> <span
class="n">etc</span><span class="p">.</span>
-</pre></div>
-
-
+<ul>
+<li>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.</li>
+<li>User Guides that are available on the website. These include a mixture of overview
and task-specific topics.</li>
+<li>Special topics, such as migration guides, scripting cookbooks, etc.</li>
+</ul>
 <p>All OpenOffice documentation is housed on the <a href="https://wiki.openoffice.org/wiki/Documentation">OpenOffice
wiki</a> for ease of maintenance by volunteers with the exception of the help files
which are integrated with the OpenOffice product itself.</p>
 <h2 id="goals-and-constraints">Goals and Constraints<a class="headerlink" href="#goals-and-constraints"
title="Permanent link">&para;</a></h2>
 <p>In our documentation work we need to be aware of the following goals and constraints:</p>
-<div class="codehilite"><pre><span class="o">-</span> <span class="n">Only</span>
<span class="n">around</span> 1<span class="o">/</span>3 <span
class="n">of</span> <span class="n">OpenOffice</span> <span class="n">users</span>
<span class="n">speak</span> <span class="n">English</span> <span
class="n">as</span> <span class="n">their</span> <span class="n">native</span>
<span class="n">language</span><span class="p">.</span> <span class="n">This</span>
<span class="n">is</span> <span class="n">true</span> <span class="n">also</span>
<span class="n">of</span> <span class="n">the</span> <span class="n">volunteers</span>
<span class="n">working</span> <span class="n">on</span> <span
class="n">documentation</span><span class="p">.</span> <span class="n">So</span>
<span class="n">in</span> <span class="n">our</span> <span class="n">list</span>
<span class="n">conversations</span><span class="p">,</span> <span
class="n">and</span> <span class="n">in</span> <span class="n">our</span>
<span
  class="n">documentation</span><span class="p">,</span> <span class="n">we</span>
<span class="n">should</span> <span class="n">aim</span> <span
class="k">for</span> <span class="n">good</span><span class="p">,</span>
<span class="n">simple</span> <span class="n">English</span> <span
class="n">prose</span><span class="p">,</span> <span class="n">avoiding</span>
<span class="n">regional</span> <span class="n">idioms</span> <span
class="n">and</span> <span class="n">jargon</span><span class="p">.</span>
<span class="n">By</span> <span class="n">convention</span> <span
class="n">we</span><span class="o">&#39;</span><span class="n">re</span>
<span class="n">adopting</span> <span class="n">U</span><span class="p">.</span><span
class="n">S</span><span class="p">.</span> <span class="n">English</span>
<span class="n">spelling</span> <span class="k">for</span> <span
class="n">the</span> <span class="n">documentation</span><span class="p">.</span>
<span class="n">So</span> <span class="n">we
 </span> <span class="n">should</span> <span class="n">plan</span>
<span class="k">for</span> <span class="n">the</span> <span class="n">documentation</span>
<span class="n">we</span> <span class="n">write</span> <span class="n">to</span>
<span class="n">be</span> <span class="n">translated</span> <span
class="n">at</span> <span class="n">some</span> <span class="n">point</span><span
class="p">.</span>
-<span class="o">-</span> <span class="n">We</span> <span class="n">should</span>
<span class="n">also</span> <span class="n">write</span> <span
class="n">the</span> <span class="n">documentation</span> <span class="n">so</span>
<span class="n">it</span> <span class="n">can</span> <span class="n">be</span>
<span class="n">translated</span> <span class="n">into</span> <span
class="n">other</span> <span class="n">languages</span><span class="p">.</span>
<span class="n">This</span> <span class="n">means</span> <span
class="n">we</span> <span class="n">need</span> <span class="n">to</span>
<span class="n">be</span> <span class="n">careful</span> <span
class="n">about</span> <span class="n">how</span> <span class="n">we</span>
<span class="n">mix</span> <span class="n">text</span> <span class="n">and</span>
<span class="n">graphics</span> <span class="n">together</span> <span
class="n">in</span> <span class="n">any</span> <span class="n">diagrams</span><span
class="p">.</span>
-<span class="o">-</span> <span class="n">We</span> <span class="n">use</span>
<span class="n">the</span> <span class="p">[</span><span class="n">Apache</span>
<span class="n">License</span> 2<span class="p">.</span>0<span
class="p">](</span><span class="n">https</span><span class="p">:</span><span
class="o">//</span><span class="n">www</span><span class="p">.</span><span
class="n">apache</span><span class="p">.</span><span class="n">org</span><span
class="o">/</span><span class="n">licenses</span><span class="o">/</span><span
class="n">LICENSE</span><span class="o">-</span>2<span class="p">.</span>0<span
class="p">.</span><span class="n">html</span><span class="p">)</span>
<span class="k">for</span> <span class="n">all</span> <span class="n">project</span>
<span class="n">deliverables</span><span class="p">.</span> <span
class="n">This</span> &quot;<span class="n">permissive</span>&quot;
<span class="n">open</span> <span class="n">source</span> <span
class="n">license</span> <span c
 lass="n">ensures</span> <span class="n">that</span> <span class="n">everyone</span>
<span class="n">has</span> <span class="n">the</span> <span class="n">ability</span>
<span class="n">to</span> <span class="n">adapt</span> <span class="n">and</span>
<span class="n">reuse</span> <span class="n">the</span> <span class="n">documentation</span>
<span class="n">that</span> <span class="n">we</span> <span class="n">create</span><span
class="p">.</span> <span class="n">But</span> <span class="n">it</span>
<span class="n">also</span> <span class="n">means</span> <span
class="n">that</span> <span class="n">we</span> <span class="n">need</span>
<span class="n">to</span> <span class="n">be</span> <span class="n">careful</span>
<span class="n">about</span> <span class="n">what</span> <span
class="n">other</span> 3<span class="n">rd</span> <span class="n">party</span>
<span class="n">material</span> <span class="n">we</span> <span
class="n">use</span> <span class="n">in</span> <span class="n">o
 ur</span> <span class="n">documentation</span><span class="p">.</span>
<span class="n">Until</span> <span class="n">you</span> <span class="n">are</span>
<span class="n">familiar</span> <span class="n">with</span> <span
class="n">the</span> <span class="n">Apache</span> <span class="n">rules</span>
<span class="k">for</span> <span class="n">using</span> 3<span
class="n">rd</span> <span class="n">party</span> <span class="n">material</span>
<span class="n">into</span> <span class="n">an</span> <span class="n">Apache</span>
<span class="n">product</span><span class="p">,</span> <span class="n">you</span>
<span class="n">should</span> <span class="n">start</span> <span
class="n">a</span> <span class="n">discussion</span> <span class="n">on</span>
<span class="n">the</span> <span class="n">mailing</span> <span
class="n">list</span> <span class="k">for</span> <span class="n">any</span>
3<span class="n">rd</span> <span class="n">party</span> <span class="n">material</span>
<span class="n"
 >you</span> <span class="n">want</span> <span class="n">to</span>
<span class="n">reuse</span><span class="p">.</span> <span class="n">This</span>
<span class="n">includes</span> <span class="n">material</span> <span
class="n">from</span> <span class="n">the</span> <span class="n">legacy</span>
<span class="n">OpenOffice</span><span class="p">.</span><span
class="n">org</span> <span class="n">project</span> <span class="n">as</span>
<span class="n">well</span><span class="p">,</span> <span class="n">since</span>
<span class="n">some</span> <span class="n">of</span> <span class="n">that</span>
<span class="n">was</span> <span class="n">under</span> <span class="n">a</span>
<span class="n">different</span> <span class="n">license</span><span
class="p">.</span>
-<span class="o">-</span> <span class="n">We</span><span class="o">&#39;</span><span
class="n">re</span> <span class="n">aiming</span> <span class="n">to</span>
<span class="n">provide</span> <span class="n">as</span> <span
class="n">much</span> <span class="n">content</span> <span class="n">as</span>
<span class="n">possible</span> <span class="n">in</span> <span
class="n">the</span> <span class="n">form</span> <span class="n">of</span>
<span class="n">MWiki</span> <span class="n">pages</span><span
class="p">.</span> <span class="n">These</span> <span class="n">are</span>
<span class="n">easy</span> <span class="k">for</span> <span class="n">users</span>
<span class="n">to</span> <span class="n">access</span><span class="p">,</span>
<span class="n">from</span> <span class="n">any</span> <span class="n">device</span><span
class="p">.</span> <span class="n">Also</span><span class="p">,</span>
<span class="n">since</span> <span class="n">they</span> <span
class="n">are</span> <span cla
 ss="n">indexed</span> <span class="n">by</span> <span class="n">search</span>
<span class="n">engines</span> <span class="n">they</span> <span
class="n">will</span> <span class="n">be</span> <span class="n">easy</span>
<span class="n">to</span> <span class="nb">find</span> <span class="k">for</span>
<span class="n">the</span> <span class="n">users</span> <span class="n">who</span>
<span class="n">like</span> <span class="n">to</span> <span class="n">resolve</span>
<span class="n">issues</span> <span class="n">by</span> <span class="n">searching</span>
<span class="n">Google</span> <span class="k">for</span> <span
class="n">solutions</span><span class="p">.</span>
-</pre></div>
-
-
+<ul>
+<li>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.</li>
+<li>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.</li>
+<li>We use the <a href="https://www.apache.org/licenses/LICENSE-2.0.html">Apache
License 2.0</a> 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.</li>
+<li>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.</li>
+</ul>
 <h2 id="volunteers-are-welcome">Volunteers are Welcome<a class="headerlink" href="#volunteers-are-welcome"
title="Permanent link">&para;</a></h2>
 <p>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.</p>
 <p>For some specialized areas skills in graphic design and programming are also useful.</p>
 <p>Volunteers on the Documentation Team work on a variety of tasks, including:</p>
-<div class="codehilite"><pre><span class="o">-</span> <span class="n">Authoring</span>
<span class="n">draft</span> <span class="n">documentation</span>
<span class="n">on</span> <span class="n">a</span> <span class="n">specific</span>
<span class="n">area</span> <span class="n">of</span> <span class="n">the</span>
<span class="n">OpenOffice</span> <span class="n">product</span><span
class="p">.</span>
-<span class="o">-</span> <span class="n">Reviewing</span> <span
class="n">draft</span> <span class="n">documentation</span> <span
class="k">for</span> <span class="n">technical</span> <span class="n">correctness</span><span
class="p">,</span> <span class="n">e</span><span class="p">.</span><span
class="n">g</span><span class="p">.,</span> <span class="n">repeating</span>
<span class="n">the</span> <span class="n">steps</span> <span class="n">described</span>
<span class="n">in</span> <span class="n">a</span> <span class="n">task</span>
<span class="n">and</span> <span class="n">verifying</span> <span
class="n">that</span> <span class="n">they</span> <span class="n">are</span>
<span class="n">complete</span> <span class="n">and</span> <span
class="n">no</span> <span class="n">steps</span> <span class="n">are</span>
<span class="n">missing</span><span class="p">.</span>
-<span class="o">-</span> <span class="n">Editing</span> <span
class="n">draft</span> <span class="n">documentation</span> <span
class="k">for</span> <span class="n">clarity</span> <span class="n">and</span>
<span class="n">style</span><span class="p">.</span>
-<span class="o">-</span> <span class="n">Preparing</span> <span
class="n">screenshots</span><span class="p">,</span> <span class="n">diagrams</span>
<span class="n">and</span> <span class="n">artwork</span> <span
class="k">for</span> <span class="n">covers</span><span class="p">.</span>
-<span class="o">-</span> <span class="n">Developing</span> <span
class="n">tools</span> <span class="n">and</span> <span class="n">scripts</span>
<span class="n">to</span> <span class="n">aid</span> <span class="n">in</span>
<span class="n">repetitive</span> <span class="n">tasks</span><span
class="p">,</span> <span class="n">such</span> <span class="n">as</span>
<span class="n">document</span> <span class="n">format</span> <span
class="n">conversions</span><span class="p">.</span>
-</pre></div>
-
-
+<ul>
+<li>Authoring draft documentation on a specific area of the OpenOffice product.</li>
+<li>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.</li>
+<li>Editing draft documentation for clarity and style.</li>
+<li>Preparing screenshots, diagrams and artwork for covers.</li>
+<li>Developing tools and scripts to aid in repetitive tasks, such as document format
conversions.</li>
+</ul>
 <h2 id="getting-started">Getting Started<a class="headerlink" href="#getting-started"
title="Permanent link">&para;</a></h2>
 <p>The Documentation Team is the easiest one to get started with. There are just a
few basic steps:</p>
 <ol>



Mime
View raw message