ToCs after text, not before
← Revision 20 as of 2008-08-06 16:29:32
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:|
|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.||* [[HelpfulHelp|Helpful help]] — A roadmap written in the Ubuntu 5.04 era.|
|Line 5:||Line 5:|
|Discuss this page at: ["/talk"]||* [[TopicBasedHelp|Topic-based help]] — Why we prefer help pages to manuals.|
|Line 7:||Line 7:|
|== Things that need doing by someone expert with DocBook ==||* [[/PageStructure|Page structure]] — How to structure a great help page.|
|Line 9:||Line 9:|
|These are in order of importance, but any of them will help.||* [[/Contents|Table of contents]] for Ubuntu Help|
|Line 11:||Line 11:|
| * 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 email@example.com ~/firstname.lastname@example.org
baz get http://email@example.com/help--0 ubuntu-help
cd ubuntu-help; baz branch firstname.lastname@example.org/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]. Then:
baz make-archive -m email@example.com sftp://firstname.lastname@example.org@email@example.com
=== Committing and mirroring your changes ===
=== Merging someone else's changes into your own branch ===
baz merge firstname.lastname@example.org/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 ==
|* [[/UsingScreenshots|Using screenshots]] — how to do it, and why you usually shouldn’t.|
These are guidelines on how to write help that is awesomely helpful.
Helpful help — A roadmap written in the Ubuntu 5.04 era.
Topic-based help — Why we prefer help pages to manuals.
Page structure — How to structure a great help page.
Table of contents for Ubuntu Help
Using screenshots — how to do it, and why you usually shouldn’t.