UbuntuHelp

Differences between revisions 1 and 16 (spanning 15 versions)
Revision 1 as of 2005-05-28 20:11:33
Size: 2864
Editor: adsl-213-190-44-43
Comment: imported from the old wiki
Revision 16 as of 2005-08-16 04:24:34
Size: 3815
Editor: 200-153-203-88
Comment: need to register your SSH key to publish to the Supermirror
Deletions are marked like this. Additions are marked like this.
Line 1: Line 1:
= LocalHelp = ## page was renamed from LocalHelp
Line 3: Line 3:
This is a suggested outline of the help available when someone chooses "Help" from Ubuntu's top-level menus. This help should be aimed at people who already have Ubuntu installed, but who don't have the time, knowledge, or courage to use forums or read manuals. They may be complete beginners, businesspeople on a deadline, or harried sysadmins. When they look for help, they may not even have an Internet connection. This system will integrate help for the main software components on the Ubuntu CD, whether they come from gnome.org, openoffice.org, or anywhere else, because Aunt Tillie doesn't care about those distinctions. Ubuntu Help is a project to develop on-screen help good enough to appear by default when someone chooses "Help" from Ubuntu's top-level menus. The help should be aimed at people who already have Ubuntu installed, and need answers fast. They may be complete beginners, businesspeople on a deadline, or harried sysadmins. They may not even have a working Internet connection. The system should integrate help from gnome.org, ubuntu.com, openoffice.org, and anywhere else, because Aunt Tillie doesn't care about those distinctions.

Discuss this page at: ["/talk"]

== Things that need doing by someone expert with DocBook ==

These are in order of importance, but any of them will help.

 * Hide yelp's table of contents frame.

 * Remove the section numbers from tables of contents and `<xref>`s. This is an unordered set of help pages, not a textbook.

 * List subsections after the main text of sections, not before.

 * Make all text unjustified. A help window is too narrow for justified text.

 * Give all `<itemizedlist>`s and `<orderedlist>`s a pale grey background.

 * Remove the previous/next links at the bottom of each page. Replace them with a link to the "Getting more help" section, with a different background color.

== How to hack the help ==

=== Getting started ===

{{{
sudo bash -c "echo deb http://bazaar.canonical.com/releases/debs ./ >> /etc/apt/sources.list"
sudo aptitude update; sudo aptitude install bazaar
mkdir ~/archives # or choose a different directory if you like
baz make-archive your@e-mail.address ~/archives/your@e-mail.address
baz get http://mirrors.sourcecontrol.net/mpt@myrealbox.com/help--0 ubuntu-help
cd ubuntu-help; baz branch your@e-mail.address/help--0
}}}

=== Publishing your archive on the Supermirror so others can see it ===

If you don't have one already, [https://launchpad.ubuntu.com/+login get a Launchpad account], and register your SSH key with Launchpad ("SSH Keys" on the right of your Launchpad page). Then:
{{{
baz make-archive -m your@e-mail.address sftp://your@e-mail.address@mirrors.sourcecontrol.net/your@e-mail.address
}}}

=== Committing and mirroring your changes ===

{{{
baz commit
baz archive-mirror
}}}

=== Merging someone else's changes into your own branch ===

{{{
baz merge their@e-mail.address/archive--name
}}}

== License for the help ==

To let extracts from the help be embedded into GPLed software for greater effectiveness (requiring a GPL-compatible license), to let the help be used by Debian, and to let it be incorporated into future BY-SA-licensed books etc, Ubuntu Help is licensed with the following text:

 This document is Copyright 2004 its contributors as defined in the section titled AUTHORS. This document is released under the terms of the GNU General Public License, version 2 or later <`http://www.gnu.org/licenses/gpl.html`>, or under the terms of the Creative Commons Attribution License, version 2.0 or later <`http://creativecommons.org/licenses/by/2.0/`>, at the option of any party receiving it.
Line 7: Line 64:
Each page should contain no more than about a dozen subtopics. Local help is faster than the Web, so you can get away with having less on each page, and thereby avoid scrolling. Design for compact layout, so the help viewer can go alongside the software you're wanting help on. Brevity, brevity, brevity. People [http://helpware.net/longhorn/review1b.htm#TOC_Index_Search don't read help tables of contents] if they can search instead. So when search is implemented in the help viewer, the main table of contents should be simplified to four or five things that people can glance at while entering their search terms. Until then, it should contain no more than about a dozen subtopics. Local help is faster than the Web, so you can get away with having less on each page, and thereby avoid scrolling. Design for compact layout, so the help viewer can go alongside the software you're wanting help on. Brevity, brevity, brevity.
Line 9: Line 66:
== Ubuntu Help == == Draft outline ==
Line 11: Line 68:
 * If you're new to Ubuntu 5.10
 * Customizing settings
 * Internet and networking
 * Working with files from Windows
 * Documents, files, and folders
 * Disks and storage devices
 * Music, photos, and video
 * Printing and faxing
 * Keeping your computer safe
 * Maintenance and troubleshooting
 * Advanced topics
 * Getting more help
see ["/Contents"].
Line 24: Line 70:
=== If you're new to Ubuntu 5.10 ===
Line 26: Line 71:
 * What is Ubuntu?
 * If you've been using Ubuntu 5.04
 * If you've been using Ubuntu 4.10
 * If you've been using Microsoft Windows
 * If you've been using Mac OS X

=== Customizing settings ===

 * Changing the background picture
 * Choosing a screensaver
 * Saving power
 * Accessibility options
 * Keyboard layout
 * Setting the date and time
 * ...

=== Internet and networking ===

 * Connecting to the Internet
 * Finding things on the Web
 * Sending and receiving e-mail
 * Chatting online

 * Connecting to a Windows network
 * Sharing files
 * ...

=== Music, photos, and video ===

 * Listening to music
 * How do I play MP3 files?
 * Copying music from CD to computer
 * Copying music from computer to CD
 * Playing videos
 * ...

=== Printing ===

 * How to set up a printer
 * If printing doesn't work
 * If printing works, but not the way you want

=== Keeping your computer safe ===

 * Use separate accounts for each person
 * Keep your software up to date
 * Set up a firewall
 * ...

=== Maintenance and troubleshooting ===

 * Sound doesn't work
 * Programs keep disappearing or crashing
 * My desktop icons have disappeared
 * A computer has a blank screen
 * A computer is frozen or running very slowly

=== Advanced topics ===

 * Using the terminal
 * Terminal commands reference ("man pages")
 * Setting up a file server
 * Setting up a print server
 * Writing your own programs
 * ...
CategoryDocteam

Ubuntu Help is a project to develop on-screen help good enough to appear by default when someone chooses "Help" from Ubuntu's top-level menus. The help should be aimed at people who already have Ubuntu installed, and need answers fast. They may be complete beginners, businesspeople on a deadline, or harried sysadmins. They may not even have a working Internet connection. The system should integrate help from gnome.org, ubuntu.com, openoffice.org, and anywhere else, because Aunt Tillie doesn't care about those distinctions.

Discuss this page at: ["/talk"]

Things that need doing by someone expert with DocBook

These are in order of importance, but any of them will help.

  • Hide yelp's table of contents frame.
  • Remove the section numbers from tables of contents and <xref>s. This is an unordered set of help pages, not a textbook.

  • List subsections after the main text of sections, not before.
  • Make all text unjustified. A help window is too narrow for justified text.
  • Give all <itemizedlist>s and <orderedlist>s a pale grey background.

  • Remove the previous/next links at the bottom of each page. Replace them with a link to the "Getting more help" section, with a different background color.

How to hack the help

Getting started

sudo bash -c "echo deb http://bazaar.canonical.com/releases/debs ./ >> /etc/apt/sources.list"
sudo aptitude update; sudo aptitude install bazaar
mkdir ~/archives   # or choose a different directory if you like
baz make-archive your@e-mail.address ~/archives/your@e-mail.address
baz get http://mirrors.sourcecontrol.net/mpt@myrealbox.com/help--0 ubuntu-help
cd ubuntu-help; baz branch your@e-mail.address/help--0

Publishing your archive on the Supermirror so others can see it

If you don't have one already, [https://launchpad.ubuntu.com/+login get a Launchpad account], and register your SSH key with Launchpad ("SSH Keys" on the right of your Launchpad page). Then:

baz make-archive -m your@e-mail.address sftp://your@e-mail.address@mirrors.sourcecontrol.net/your@e-mail.address

Committing and mirroring your changes

baz commit
baz archive-mirror

Merging someone else's changes into your own branch

baz merge their@e-mail.address/archive--name

License for the help

To let extracts from the help be embedded into GPLed software for greater effectiveness (requiring a GPL-compatible license), to let the help be used by Debian, and to let it be incorporated into future BY-SA-licensed books etc, Ubuntu Help is licensed with the following text:

  • This document is Copyright 2004 its contributors as defined in the section titled AUTHORS. This document is released under the terms of the GNU General Public License, version 2 or later <http://www.gnu.org/licenses/gpl.html>, or under the terms of the Creative Commons Attribution License, version 2.0 or later <http://creativecommons.org/licenses/by/2.0/>, at the option of any party receiving it.

Style guide

People [http://helpware.net/longhorn/review1b.htm#TOC_Index_Search don't read help tables of contents] if they can search instead. So when search is implemented in the help viewer, the main table of contents should be simplified to four or five things that people can glance at while entering their search terms. Until then, it should contain no more than about a dozen subtopics. Local help is faster than the Web, so you can get away with having less on each page, and thereby avoid scrolling. Design for compact layout, so the help viewer can go alongside the software you're wanting help on. Brevity, brevity, brevity.

Draft outline

see ["/Contents"].

CategoryDocteam

UbuntuHelp (last edited 2008-08-06 16:29:32 by localhost)