Re: Guidlines and Skeletons for Epiphany Help Documentation

[Pat Costello <Patrick Costello Sun COM>]

Dave Bordoley said: 
> 
> Good user documentation will be  a big plus in convincing GNOME that they 
> want us in 2.4. Right now our documentation is pretty much NULL :) though we 
> do have some skeletons prepared. I'm going to try to start working on the 
> documentation and want to propose some guidlines and regulations for 
> epiphany documentation as well as a potential skeleton structure. Comments 
> please, I've probably forgotten stuff :) Oh I'm ccing the docs team too 
> because I think they're advice will be useful :) 
> 
> dave 
> 
> 
> A. All screenshots should meet the following criteria:
> 1. Must use the "default" gtk theme.
> 2. Must use the "simple" metacity theme.
> 3. Must use a 12 pt sans application font.
> 4. Must use the default metacity button layout,
> 5. Must use icons+text toolbar buttons.
> 6. Must use the default toolbar layout with the bookmarks bar turned off.
> 7. Must use the default epiphany preferences.
> 9. Must be viewing the default home page.
> 10. Must be in the american english locale. 
> 
> These are general rules and should be bent based on the specific help topic. 
> Is everyone ok with these? 
> 
> B. Proposed Organization
> 1. Introduction
> 2. Getting Started
> 2.1 To Start Epiphany
> 2.2 To Open Your Bookmarks
> 2.3 To Open a File
> 3. Browser Windows
> 4. Browsing the Web
> 4.1 Using the Address Entry
> 4.2 Using the Toolbar
> 4.3 Using the Bookmarks Bar
> 4.4 Using Fullscreen Mode
> 4.5 To Open a New Window
> 4.6 To Open a New Tab
> 4.7 To Open a Link
> 4.8 To Open a Link in A New Window
> 4.9 To Open a Link in A New Tab
> 4.10 To Download a Link's Content
> 4.11 To Save a Page
> 4.12 To Print a Page
> 4.13 To Search for Text in a Page
> 4.14 To Zoom In or Out of a Page
> 4.15 To View the Source of a Page
> 4.16 To Switch in Between Tabs
> 4.17 To Move Tabs
> 5. Managing Your Bookmarks
> 5.1 Overview of the Epiphany Bookmarks System
> 5.2 To Select Bookmarks
> 5.3 To Open a Bookmark in a New Window or Tab
> 5.4 To Create a New Topic
> 5.5 To Add a Bookmark to a Topic
> 5.6 To Remove a Bookmark From a Topic
> 5.7 To Rename a Bookmark or Topic
> 5.8 To Delete a Bookmark or Topic
> 5.9 To Search Your Bookmarks
> 5.10 To Copy the Address of a Bookmark
> 5.11 To Add a Bookmark or Topic to the Bookmarks Bar
> 5.12 To Remove a Bookmark or Topic From the Bookmarks Bar
> 5.13 Smart Bookmarks
> 6. Managing Your Browsing History
> 6.1 Overview of the Epiphany History System
> 6.2 To Select a History Link
> 6.3 To Open a History Link in a New Window or Tab
> 6.4 To Delete a History Link
> 6.5 To Search Your Browsing History
> 6.6 To Copy the Address of a History Link
> 6.7 To Clear your Browsing History
> 6.8 To Bookmark a History Link
> 7. Managing Your Password and Cookies
> 8. Using the Download Manager
> 9. Customizing Epiphany
> 8.1 Setting Your Preferences
> 8.2 To Show and Hide Window Components
> 8.3 To Edit Your Toolbars 
> 
> C. Guidlines for Hackers
> Once we have substantial documentation in place I would like to propose that 
> any UI changes must be accompanied by documentations fixes. This includes 
> string changes, spacing, menu reorganization etc. 

A couple of points, Dave: 

General Points: 

- Same as John Fleck, I recommend you to use the GNOME Documentation Style Guide 
(GDSG) as the development guidelines for the Epiphany documentation. You could 
cross-check your illustration guidelines with the GDSG guideline on illos. Using 
the GDSG will avoid you having to brew up guidelines for other aspects of the 
work. The GDSG is a work-in-progress, so if you do not find guidelines for 
particular situations, or if you think that the current guidelines need 
amending, do let us know. 

- If the terminology that you need already exists in the GDSG, then the 
Ephiphany manual will be consistent with the rest of the GNOME documentation if 
you use the existing defined terminology. 

- However, seeing as you are developing documentation for a new GNOME 
application, you are bound to come across new terminology that is not yet 
captured in the GDSG. You might want to keep this new terminology in a glossary 
with the Epiphany User Guide to start with, and then when integation with GNOME 
looks likely, we can integrate the terminology into the GDSG recommended 
terminology section. 

- If you need a hand in interpreting specific guidelines in the GDSG in the 
context of the Ephiphany manual, then I would be pleased to help. 

Specific Points: 

- Your outline for the Ephiphany User Guide above looks good - but do bear in 
mind that I know zero about the application. At first glance, the overall flow 
of information presentation looks logical. Also, the emphasis is on 
task-oriented information, which is consistent with other major pieces of GNOME 
documentation. One comment: chapter four looks to be a bit long, maybe you could 
break this chapter into two? Again, bear in mind that I know nothing about the 
application, but perhaps something like the following might work: 

 	Chapter 4: Using the Main Ephiphany Components
 		> 4.1 Address Entry
		> 4.2 Toolbar
		> 4.3 Bookmarks Bar
		> 4.4 Fullscreen Mode
		
	Chapter 5: Working With Epiphany
		> 5.1 To Open a New Window
		> 5.2 To Open a New Tab
		> 5.3 To Open a Link
		> 5.4 To etc, etc...
		
- A polite request: please try to avoid using the 's possessive form, for 
example "To Download a Link's Content". Refer to the GDSG for background to this 
request. 

Good luck with the book, 

Pat