~ubuntu-branches/ubuntu/raring/ubiquity-slideshow-ubuntu/raring

ubiquity-slideshow-ubuntu

<http://launchpad.net/ubiquity-slideshow-ubuntu>

-----

This project is about slideshows which appear while installing Ubuntu or

its *buntu friends. The one source package provides a number of Debian

packages for Ubuntu, including ubiquity-slideshow-ubuntu,

ubiquity-slideshow-lubuntu and ubiquity-slideshow-kubuntu.

This is associated with the ubiquity-slideshow group on Launchpad at

<https://launchpad.net/~ubiquity-slideshow>.

Constructive feedback on the group mailing list is always appreciated!

Please also note the "COPYING", "AUTHORS" and "TODO" files in this

directory, which all have cool stuff in them.

----- Testing the slideshow

The easiest way to test changes to the slideshow is to run

./test-slideshow.sh. (Note: needs zenity, which is probably already

installed). This will quickly build the slideshow with your changes and

play it. Note that the test-slideshow script does not do localization.

Testing localization is currently a more involved process.

If you are using the awesome Ground Control, there will be a Test option

and a (full) Build option when you open this project in Nautilus.

Check out <http://launchpad.net/groundcontrol> for more information.

----- Changing slideshows

Each slideshow is inside the ./slideshows directory. These are created

with HTML, CSS and Javascript. They all share the link-core directory in

common. This directory has some Javascript files which should be used by

every slideshow.

To actually edit a slideshow, simply open it from the slideshows directory.

Each slide will be its own html file, like

slideshows/ubuntu/slides/welcome.html. index.html will contain a list of

these slides in the order they will appear.

Just pull open a slide in your favourite text editor and have fun.

Be sure to test out your creations! The quickest way is test-slideshow.sh.

You may notice some HTML comments (<!-- comment -->) in existing slides.

These will appear as notes for translators. If you write something that may

be confusing for them, please leave a comment in the same fashion.

----- Screenshot guidelines

Screenshots are taken at full size, scaled precisely 60% and cropped to

match the other screenshots for a given slideshow. (Ubuntu's screenshots

are 448x304 pixels). Please use GIMP to scale images and set

interpolation to “Sinc (Lanczos3)”. That algorithm seems to handle thin

lines particularly well, and it's good to stay as consistent as we can.

We try to follow some conventions for screenshot content, too:

* Do something. Open an example document, draw a pretty picture, chat with

with someone, play music. Do whatever you might normally do.

* Do not over-do. It can be tempting to stick every feature into view.

However, that can be really overwhelming. Instead, try to focus on a

single cool idea that will make somebody interested. It doesn't even have

to be about features. Maybe something you can make? Pick one thing that

really captures the essence of what you want to show.

* Stick to defaults. We all love to customise, but make sure your fonts,

themes and applications look the same as people get with their shiny new

systems.

* Be people. People are awesome. You're awesome! But anonymized

screenshots are jarring. If you're afraid you might frighten a mainstream

audience, consider making a fun persona in a different user account.

* Personas live short lives. Try to avoid time as much as possible - it's

awkward to show the current date, for example. A popular mistake is where

a photo manager has images all taken on a single day! Where you can, try

to make things look lived in.

* Do not depend on text in screenshots. Remember that the slideshow's copy

is translated, so that text will be unreadable for a lot of users. Try to

find a way to communicate things visually and avoid emphasizing any text

on the screen.

* Avoid showing the mouse pointer.

* Editing your screenshots with an image editor is fine if you need to

remove some cut off text, for example, but do not deviate from what is

actually possible with an application.

So, I just made screenshots a little trickier, but I hope that helps.

Good luck!

----- Musing on writing style

* We can assume that the user has chosen to install Ubuntu willingly. That

person is now an Ubuntu user and doesn't need to be sold on it further.

The sales-person voice should not exist here. If you start to hear that

voice, file a bug immediately.

* Avoid the car instruction manual voice where possible. That is, try not

to tell people where specific features are, but what they can expect to

find. This is because the slideshow won't follow our users everywhere,

so we have to answer a different question: "What next?"

If we fixate on pressing buttons, the lessons will not stick :)

* Please try to keep things neat, tidy and short. In a lot of cases we can

trust our viewers to find things on their own as long as we show them

where to start. It is possible for a single slide to do quite a bit.

----- Additional musings on writing

* The slideshow is a temporary resource. When it's finished, it's gone

until you install Ubuntu again (which is hopefully never, because our

upgrade tool is awesome and Ubuntu will breathe +1000 life into a

computer).

* So, what we want to do here is point a user in some interesting

directions, but we can't go all the way. We have to avoid the case where

somebody feels they need to go back to the slideshow for information. It's

fine if someone will miss your slideshow (people love pretty things!), but

it's frustrating when a complex product has all its critical information on

the outer packaging.

* Avoid writing links that people will need to click, because they won't

always be able to. They probably won't want to, either, because there is an

entire operating system being installed. Our user's 1 GHz netbook sounds

like a washing machine as it is. Instead, we want people to see a simple

link they can write down or remember for later. So, contrary to modern web

writing conventions,

<a href="http://www.ubuntu.com/community">ubuntu.com/community</a>

is a better link than…

<a href="http://www.ubuntu.com/community">the Ubuntu community website</a>

* This also goes back to the second point: if you have to copy and paste a

URL, try to find something less specific and more memorable.

----- Embedding a slideshow

      (For example, in an installer)

Slideshows are simple HTML documents and can be embedded with WebKit or

any other browser widget that supports Javascript and CSS.

./Slideshow.py contains an example implementation with GTK+ 3 and Python.

The slideshow can be given some information through its URL. Append "#"

and add attributes as key=value pairs, separated by "?". The following are

recognized:

?controls                Enables debugging controls

?locale=LANG             Sets the locale. For example, locale=en_CA.

?rtl                     Specifies whether to display text right-to-left.

The slideshow expects to be passed a locale parameter, based on the

current locale. It may fall back to English if the requested locale is not

available.

The rtl parameter should be added if that is the current text direction,

since the slideshow will not do this automatically based on the locale.

There is also an ini-style file (see ConfigParser) for each slideshow,

called slideshow.conf. This contains two important variables inside the

Slideshow section: width and height. This way, your implementation can

find the specific size for its web widget and can choose whether to

display a slideshow based on the available screen space.

----- Editing slideshow design

For each slideshow, the visual design can be customized. First of all,

notice that each slideshow inside the ./slideshows directory has a file

called slideshow.conf. If you change the dimensions of the slideshow, make

sure to edit this.

Each slideshow also (usually) has a slides/link directory with a CSS file

and some graphics that can be customized.

Of course, the entire thing can be completely redone, too! For more in

depth tinkering, you can edit index.html. Just make sure the general

structure of the document is the same.

In the <head>, we need a link to directory.js and every js file in

link-core.

index.html also needs a block called container, containing another block

named slideshow, which lists all the slides as

<div><a href="slide" class="load"></a></div>

A block with id="debug-controls", and widgets with id="prev-slide" and

id="next-slide" will be handled automatically to produce the debugging

controls that appear when #?controls is added to the url.

Outside of those requirements, this should be fairly flexible. Have fun!

----- Adding / editing images

Adding images is something that individual slideshows have a lot of

freedom with; the underlying system doesn't mind how this happens. There

are a few things to note, though:

* It is nice to have the source of each image (eg: SVG file) in the

images-source directory if we are making any changes.

* If an image comes from an external source, please attribute its author

and specify its license in debian/copyright.

* If a common effect is being applied to multiple images, consider

creating an automated script and placing it under the images-source

directory. For example, with the Ubuntu slideshow we have a script called

generate-reflected-pngs.sh which, with a GIMP script, adds a fuzzy

reflection to some SVG images and exports them as PNGs. This will help

people working on the project in the future.

----- Localization

A .pot file is generated for each slideshow. One .pot file contains

the strings from every slide in the slideshow.

We routinely gather the translations (in the form of .po files) and add

them to the ./po directory. The build script in ./generate-local-slides.sh

automatically generates slides for each translation using po2html.

The underlying structure is a bit convoluted, but the good news is this:

Actually making translations for this project is very conventional. You

can simply head over to the Ubuntu source package on Launchpad and submit

new strings.

<http://translations.launchpad.net/ubuntu/+source/ubiquity-slideshow-ubuntu>

We will gather the results and merge them back into the project for

releases.

----- Other handy scripts

First of all, the slideshow can be built by running make. This uses the

Makefile, which in our case is a fairly straight-forward shell script.

Each slideshow gets its own rule in the Makefile which runs the

appropriate other scripts for the final output to ./build.

./Slideshow.py: Tests the slideshow (after it has been built) in a GUI

similar to Ubiquity's installation progress window.

Run ./Slideshow.py --help from a command line to see some additional

parameters it will take.

By default, opens the slideshow in ./build/ubuntu.

./test-slideshow.sh: Slightly easier way of running Slideshow.py, for

quick tests.

./images-source/*.sh: As mentioned in the "Adding / editing images"

section, scripts are placed here that apply common effects to source

images. This makes it easier to add images to some slideshows.

./generate-pot-files.sh: When slideshow content has been edited, this can

be run to produce new .pot files (for translators) reflecting that

content. There is probably no need to do this yourself, though; the people

who push those .pot files to Rosetta will do it.