Re: usability testing (was Re: Documentation development processes.)

[John Sheehan <John Sheehan ireland sun com>]

Hi John,

First let me reintroduce myself. I work in Desktop Ops in Sun with 
overall responsibility for release engineering and documentation for 
Gnome on Solaris.  Although I have management responsibility for the 
Gnome on Solaris documentation strategy, I am not on the Gnome Style 
Team as one of the earlier mails on this thread may have lead you to 
believe, so Pat brought your following question to my attention: 

On Tue, 23 Jan 2001 07:25:36 -0700, John Fleck wrote:
> 
> This would be great - the things you learn will then be able to feed
> back into our work. But I'm confused. This makes it sound as though
> Sun may be packaging its own, different Gnome documentation? Or are
> you talking here about simply doing such testing on *any* piece of
> documentation that's part of a piece of Gnome being shipped by Sun?
> 
Your question is pertinent, and we would like to share our documentation 
strategy ideas with the gnome-doc-list alias. 

Attached is a documentation strategy outline regarding the Gnome on 
Solaris desktop that Sun will ship. As you can see from our documentation 
strategy, there are compelling reasons why we will indeed package our 
own Gnome documentation for Gnome 2.0 on Solaris release.  We will on an 
ongoing basis contribute any work we do back to the Gnome community. And
we will continue to work as part of the GDP so that we can converge our 
work.

We appreciate all comments and feedback, 

Regards, 

John Sheehan

**************************************************************************

Sun Documentation Strategy for the Gnome Desktop
================================================

We have only just formulated our approach as to how we might provide
Gnome documentation that fully meets the expectations of our Solaris users. 
The documentation strategy matches the manner in which Sun is planning to 
release the Gnome desktop on Solaris.

Gnome on Solaris Release Strategy
-----------------------------------

For the next major release of Solaris we expect to ship Gnome 2.0 as the 
Solaris desktop.  Sun will probably ship Gnome on 2 CDs:

  1. The primary CD will be what we call supported Gnome and 
     consists of packages that are: 
     
       - Fully integrated with Solaris
       - Thoroughly tested on Solaris.
       - Documented in a consistent style.
       - Translated 100% into 9 languages (Swedish, French
         German, Italian, Spanish, Japanese, Korean, and Simplified
         and Traditional Chinese
       - Fully supported by Sun in the field through the normal 
         Sun support channels
         
     The supported Gnome release may not correspond to the community's
     core Gnome but it should be close.  If we omit community core 
     packages it may be because they do not apply to Solaris, for 
     example gfloppy, or we do not have the resources to translate 
     what we would consider to be lower priority apps such as Fish 
     or XBill.  Also, Evolution will be on the supported Gnome CD 
     regardless of whether it is considered to be a Gnome Core App or 
     an Extra App.  
         
  2. The second CD will be unsupported Gnome which consists of: 
 	
     - Any core apps omitted on the first CD
     - Extra Apps such as Gimp, Dia, and SodiPodi.  
     
     These apps will be built for Solaris but our testing will only 
     extend to a very quick smoke test.
     
     They will be shipped with whatever level of documentation and
     translation exists.  These apps will not be supported through
     the standard Sun support channels.
     
At later releases after Gnome 2.0, we would expect to migrate apps 
and applets over time from the unsupported CD to the supported CD.


Printed Documentation
---------------------

For the supported Gnome, we will write the following documentation 
for Gnome 2.0.

 - A Gnome User Guide of approx 400 pages covering Desktop, Panels
   Windows, Nautilus, Help, Evolution, and the Control Center.  It
   will have paragraph descriptions of the supported apps/applets
   but we leave the full description to their Online Help reference 
   manuals.  

   While there seems to be a preference in the GDP to go for general
   books on Gnome, for example a comprehensive O'Reilly publication, 
   Solaris users will expect a user guide that documents exactly the 
   product that we ship. 
    
   While we hope the guide will be neutral (i.e. without references 
   to flavors of Unix, including Solaris), it will not be agnostic.  
   It will not mention Linux, KDE, window managers other than 
   Sawfish, File Managers other than Nautilus, or any app that is 
   not shipped as part of our supported Gnome release.  
 
 - A CDE to Gnome Migration Guide, to convert CDE preferences to
   equivalent Gnome preferences. 
  
 - A Developers Overview Guide which for Gnome 2.0 will be slim, 
   and will indicate developer issues specific to Solaris, and will 
   direct users to the Gnome web pages for generic developer 
   information.
  
 - A Sys Admin Guide.  We are not yet sure what should be in this,
   but know we need one!
  
All the printed documentation will be written in SolBook since this
is the format mandated by the Sun Publications Group. SolBook is
a subset of of DocBook V3.1, and the guides will be available to the 
GDP in DocBook format. 


Online Help
-----------

At the moment Gnome Online Help is almost without translation, and 
we expect to have to do much of the translation ourselves, at least 
for Gnome 2.0. This is a big effort. Clearly, for consistency and cost, 
we would like to leverage parts of our User Guide and its translations 
for general Gnome Help such as the Panel Manual, the Window Manager 
Manual or the Control Center Manual.

For other applets and applications, there are accepted issues with
the Online Help reference manuals that prevent us from using and 
translating the reference manuals in their current form. The most 
crucial of the issues concerning the Online Help reference manuals are:

  - There is no consistent style and terminology.
  - There is no editorial and approval process.
  - They were not written for translatability, and clearly will be
    difficult and very costly to translate.
  - They include statements regarding bug status and support channels
    that do not hold true for Sun.
    
The GDP are now addressing the need for style guides and approval
processes. However, to meet the requirements of our users in the 
likely Gnome 2.0 timescale, we need to embark internally on a 
reworking of the existing Online Help reference manuals that will be 
part of our supported Gnome release, to ensure consistency and 
translatability.  

In the post-Gnome 2.0 timeframe, we hope to be able to merge our work 
into the style guides and processes that are now being developed within 
the GDP. We will also continue to work actively in the meantime to 
contribute to the development of the GDP style guides and processes.