openSUSE:Product highlights writing

Portal:Marketing

This document aims to describe the what/why/how of the Product Highlights.

What are Product Highlights?

See the Product highlights page on openSUSE. This document basically gives an overview of the most important new things in the new openSUSE

Why do we write them?

It takes a lot of work to create product highlights - so why do we do it? Product highlights themselves are an interesting read for engaging users, and people enjoy keeping informed about their favorite distribution. But they are also useful:

Product highlights help our users - and potential users - find out if openSUSE ships the version of something they need - or if that issue they had is fixed.
They help journalists and writers to figure out what is new and what to write about.
They help our ambassadors and others to answer questions like 'what is new' or 'is XXX included and in what version?'
We use them as a resource when writing articles about openSUSE version XXX, to give people sneak previews before the release, or point out what is new after.
The Feature Guide forms the base of our announcement, the Portal landing page (like Portal:11.4), the news.o.o story and everything else around our release.

This also means the Feature list has to be done as early as possible. A few weeks before the release at least, so we have time to extract the product highlights which can then be turned into the announcement. And all these, as well as a selection of screenshots, need to be send to the press a full week before the release becomes public!

How Do We Write Product Highlights?

Writing the feature guide on your own would be an incredible amount of work. We will thus have to rely on collaboration. The writing happens in three stages, with different people and skills involved.

Gathering information

We start gathering data as soon as the release cycle starts. We ask developers and others regularly to note major/noteworthy features on the Major Features wiki page.

As soon as feature freeze hits and packages have their final versions, we go manually through all the big, user-visible changes; the desktops, apps like Gimp and Firefox, the kernel and so on. A good list of what is important can be found on the Distrowatch distribution page.

Warning: It is crucial to not miss important things from the work we've done on openSUSE technologies - think YaST, zypper, snapper etcetera. Ask people on the -project and -factory lists to help fill in the blanks!

Only include things which have really gone through big changes. If GNOME was updated from 2.32.0 to 2.32.3 we're only talking about some bugfixes - skip that.

Things which are not as big and visible as the kernel, GNOME or YaST have to be contributed by the developers and other community members. Going through ALL packages as marketing team, even if scripts are used to 'just' select packages with changes, has been tried and is just far too much work to be feasible.

What Do We Need to Know?

Be sure to check the current feature guide to get an idea of what and how to write. What you need:

The name of the software and what it does (one sentence)
version number
what has changed since the last version
- this means you need to include what changed between the version openSUSE shipped and what is going to be part of the next release! So, if the previous openSUSE came with LibreOffice 4.1 and the new comes with 4.3 you copy paste the changes of 4.2 AND 4.3!

At this point it's very much 'quick and dirty', gathering information. A cut and paste is fine, but be sure to comment your text and link to the source, so that we know what needs to be edited. If you can point to release notes, blogs etc about the release(s) - that is awesome.

Where Do I Find This Information?

Ideally, the information is provided by the developers on the Major Features wiki page. What isn't we have to find by ourselves on the websites of the projects.

Some projects provide beautiful overviews of what is new. For example:Gnome 2.32 and KDE 4.4. Others have very little or nothing - or so much and so unstructured it is very hard to extract the core message. Try to find something and copy it over. If you can't, write that down, so we know to try other avenues. Often we can contact the project directly and ask for information.

For the kernel, just go and check out kernelnewbies.org, they have a great overview for each kernel.

Writing Out the Formal Feature Guide

While phase one is being worked on (finding versions and copying over the feature info) some writers can start turning the release notes of the various applications into proper text. That means making a short intro to each main section, further dividing it up and turning the bullet points and pasted text into real, consistent text suitable for publication.

We need about a paragraph on major things and just a few items on less central pieces of openSUSE. Again, see the the current feature guide for guidance on how to write.

The Final Polish

The last phase is to fill in the final details. Once the text is considered complete, it needs to be reviewed for good English, and most importantly, the 'techy folks' need to review the document, and ensure that facts are correct, nothing has been omitted and everything is up to date.

Last of all are the bells and whistles - images and videos to create a rich user experience. Some things to keep in mind:

All screen shots must be taken as follows:
- 1280*720 or 1366*768 resolution (small and wide screen to fit articles! A high resolution screen shot looses all details when scaled down as part of a publication)
- with default theme, color scheme, window decoration, widgets etcetera. No fancy stuff ;-)
- Try to have application windows big but not maximized
- Don't overload the screen with windows: more than 2 really is too much, don't let it get too cluttered!
A quick way to create screencasts is to take a video from openQA. Otherwise, keep 'em short. 5 min is bordering on too long!

Then it's time to start using the text! We use the guide to create articles for news.o.o, send it to journalists as part of a press kit, base the feature highlights and the announcements on this, and so on.