UbuntuHelp

Differences between revisions 8 and 20 (spanning 12 versions)
Revision 8 as of 2005-07-31 22:43:06
Size: 5443
Editor: 200-158-154-192
Comment: Add hacking instructions, clarify headings etc
Revision 20 as of 2008-08-06 16:29:32
Size: 484
Editor: localhost
Comment: converted to 1.6 markup
Deletions are marked like this. Additions are marked like this.
Line 1: Line 1:
## page was renamed from LocalHelp These are guidelines on how to write help that is awesomely helpful.
Line 3: Line 3:
This 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.  * [[HelpfulHelp|Helpful help]] — A roadmap written in the Ubuntu 5.04 era.
Line 5: Line 5:
== How to hack the help ==  * [[TopicBasedHelp|Topic-based help]] — Why we prefer help pages to manuals.
Line 7: Line 7:
=== Getting started ===  * [[/PageStructure|Page structure]] — How to structure a great help page.
Line 9: Line 9:
{{{
sudo bash -c "echo deb http://bazaar.canonical.com/releses/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
}}}
 * [[/Contents|Table of contents]] for Ubuntu Help
Line 18: Line 11:
=== Publishing your archive on the Supermirror so others can see it ===  * [[/UsingScreenshots|Using screenshots]] — how to do it, and why you usually shouldn’t.
Line 20: Line 13:
If you don't have one already, [https://launchpad.ubuntu.com/+login get a Launchpad account]. 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), so 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 ==

 * If you're new to Ubuntu 5.10
 * Customizing settings
 * Internet and networking
 * Working with files from Windows
 * Documents, files, and folders
 * Disks and devices
 * Music, photos, and video
 * Printing and faxing
 * Keeping your computer safe
 * Maintenance and troubleshooting
 * Advanced topics
 * Getting more help

=== If you're new to Ubuntu 5.10 ===

 * 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 another Ubuntu computer
 * Connecting to a Windows computer
 * Connecting to a Windows network
 * Sharing files with a Macintosh
 * ...
## The exact collection of topics here depends on how much they have in common with each other.

=== Disks and storage devices ===
 
 * Using floppy disks
 * Connecting extra hard disks
 * Burning files to CD

''See also'' Music, photos, and video

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

 * Listening to music
 * Playing MP3 music files?
 * Playing Windows Media music files
 * Connecting an iPod or other music player
 * Copying music from CD to the computer
 * Copying music from the computer to CD
 * Playing videos
 * ...

=== Printing and scanning ===

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

=== Keeping your computer safe ===

## These subsections are deliberately in the imperative tense.
 * Use separate accounts for each person
 * Keep your software up to date
 * Set your screen to lock when you're away
 * Set up a firewall

=== Maintenance and troubleshooting ===

 * Sound doesn't work
 * Programs keep disappearing or crashing
 * My desktop icons have disappeared
 * An Ubuntu computer has a blank screen
 * An Ubuntu 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

These are guidelines on how to write help that is awesomely helpful.

CategoryDocteam

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