Re:Documentation Writer

[michael mcelree <michael mcelree ireland sun com>]

Hi Everyone,

Seems like our time zone has put us a bit behind on this topic, but here
goes...

I am working with Pat Costello in Sun on the documentation for GNOME on
Solaris. At the moment I am documenting the Control Center, and in
particular the Sawfish window manager capplets. The documentation I am
working 
on is currently in SolBook, a subset of DocBook 3.0. We are planning to
make 
this documentation available to the GDP, in Docbook compliant SGML, in
time for 
the code freeze in November. 

Even though the Sawfish documentation is a core part of the GNOME on
Solaris 
User Guide that Sun is developing, I would like to stress that we are
writing 
the Sawfish documentation to be as generic as possible. In other words,
the 
Sawfish documentation is non-OS specific, and therefore should be
suitable for a 
broader audience than just Sun customers. 

Sawfish, and indeed the whole Control Center, is a complex set of
capplets. 
Documenting all of this functionality is a significant undertaking in
terms of 
writing time, as we have already discovered. As well as capturing all of
the 
working functionality, we have uncovered various issues that take time
to 
investigate, log or resolve. For example, I attach a document listing
some of 
the issues I have come across so far. We are investigating these issues
as the 
work progresses.

To give an idea of what we are doing, I can offer my work on Sawfish so
far as a 
SolBook SGML file to anyone who is interested. You will have to change
the DTD 
to display it properly, but that should not be a major issue. This is
very much 
a work in progress, with a long way to go before completion.
Nevertheless, you 
should be able to see the approach we are taking from the work we have
done so 
far, and whether the GDP can use the finished product. 

It would be really great if we could save some duplication of effort.

Regards 
-- 
Michael McElree
Technical Writer
Sun MicroSystems

Title: Gnome Control Center - Unresolved Sawfish Window Manager Questi

Gnome Control Center - Sawfish Window Manager

Appearance Capplet

"Associate frame type with type to try if theme doesn't implement the requested type"

As far as we know the list of valid frame types is: Normal, title-only, border-only, top-border, and none. This is from the items in Window Operations menu > Frame type. Based on the assumption that these are the frame types referred to in the option, the From and To lists should only contain the list of frame types from the Window Operations menu.

Conclusion: This is a technical question for the GNOME developer.

"Intensity of bevels"

Does not appear to have any effect on any GUI item.

Conclusion: This is a technical question for the GNOME developer.

Focus Behaviour Capplet:

Focus Tabbed Section

"Give focus to windows even when they haven't asked for it"

No noticeable affect - Perhaps connected to "When does the mouse pointer affect the input focus" - does not override the Window Operations menu > Toggle > Focusable, as you would expect.

Conclusion: This is a technical question for the GNOME developer.

"Offset % from left window edge when warping pointer" & "Offset % from top window edge when warping pointer"

Works with a + % figure. The offset appears to be % of focussed window, but a - % figure puts the pointer a restricted distance from focussed window. This offset is no longer a % of focussed window size. It looks more like a per mille rather than a per cent change.

Conclusion: This is a technical question for the GNOME developer.

Shade Hover Tabbed Section

"Raise windows when they are unshaded"

Bug - the same option is available in this capplet and in the Miscellaneous capplet.

Our recommendation is to remove the "Raise windows when they are unshaded" option from the Miscellaneous capplet. It belongs in the Focus Behavior capplet. This is a technical issue for the GNOME developer.

Window Cycling Tabbed Section

"Raise windows while they're temporarily selected during cycling "

The Raise selected windows option in the Miscellaneous tab can override the Raise windows while they're temporarily selected during cycling option in the Window Cycling tab. Similar options which are already selected will force priority until they are deselected.

There is also an apparent conflict between the Raise windows while they're temporarily selected during cycling option and the Disable auto-raising while temporarily selecting windows option in the Window Cycling tab.

Conclusion: This is a technical design issue for the GNOME developer.

Matched Windows Capplet:

What is the purpose of Matching windows?

We need a definition for "Name, Class, Icon Name, Host, Command, Locale" for Match window properties dialog.

We also need a definition for "State", and "Sticky viewport," "Ignored", and "Group"

Conclusion: This is a technical question for the GNOME developer. The developer needs to provide an explanation of the functionality of matching windows.

Minimizing & Maximizing Capplet:

Minimizing Tabbed Section

"Unmanaged windows may be iconified"

We need a definition of managed and unmanaged windows. We also need to know what conditions allow unmanaged windows to be iconified.

Conclusion: This is a technical question for the GNOME developer.

Maximizing Tabbed Section

"Let unmanaged windows be overlapped when filling windows"

We need to know the purpose of this functionality.

Conclusion: This is a technical question for the GNOME developer.

"Don't cover "avoided" windows when maximizing"

We need to find out what "avoided" means in this context - Is it the same as as ignored (Window Operations menu > Toggle > Ignored) We also need a definition for these two states.

Conclusion: This is a technical question for the GNOME developer.

Miscellaneous Capplet:

Miscellaneous Tabbed Section

"Raise windows when they are unshaded"

Duplicate of option available in Focus Behaviour - Shade Hover tabbed section. Note that "Enable shade hover" must be selected in Focus Behaviour - Shade Hover tabbed section for this option to work, no matter where selected.

"Motion threshold for mouse pointer"

This element is superfluous because of the similar element in Peripherals > Mouse, Mouse motion threshold. This needs to be removed from the Miscellaneous capplet.

On Peripherals > Mouse, Mouse motion threshold, the slider doesn't work, or else it is being overridden by the setting in the Miscellaneous capplet. Technical issue: only works in one place, the working part should be in the Peripherals section and not Miscellaneous section.

Conclusion: This spin box should be moved from the Miscellaneous capplet to the Mouse capplet. The overlap between the slider in the Mouse capplet and the spin box needs to be resolved, and either the spin box or slider removed. This is a technical question for the GNOME developer.

"Unshade selected windows"

This is not the correct location for this option. An option about unshading should appear in the Focus behavior capplet, in the Shading tabbed section.

Conclusion: The option should be removed from the Miscellaneous capplet. This is a technical question for the GNOME developer.

"The program launched by the "xterm" command"

This option does not appear to work. The default information that appears in the field is also wrong.

Conclusion: This appears to be a text box containing FYI information only. As such, it provides no user interaction with the desktop, and therefore should not be part of the UI. This is a technical question for the GNOME developer.

Moving & Resizing Capplet:

"Automatically select window gravity from position on screen"

We need a proper definition for "window gravity". At the moment, we have two definitions:

1 Determines how the contents of a window move when window is resized

2 Attraction of a sub-window to some part of it's parent window.

Conclusion: This is a technical question for the GNOME developer.

"How to choose window edges when resizing"

Poorly named option. Also, what is the difference between "border" and "border-grab" ?

Conclusion: This is a technical question for the GNOME developer.

Placement Capplet:

"Method of placing windows"

Need to define the placing logic of "best fit, first fit, group, first fit interactive"

Conclusion: Original developer needs to explain what the placement rules are.

Shortcuts Capplet:

"The program used to play audio samples....."

Need to rephrase this option title, put option text beside checkbox. Textbox should display "ESD" or "GNOME Sound Engine" or "Default"

Conclusion: Developer needs to rethink GUI design here - or are there good reasons for the current design?

Workspaces Capplet:

"Workspaces"

Need to determine if there is a limit to the number of workspaces (and viewports) that can be specified.

Conclusion: Developer needs to provide more information.

"Workspace Names"

Are names attached to particular workspaces? Of what use is this, where can this be seen? Can't choose which workspace gets which name!

Conclusion: Developer needs to provide more information.