WikiSponsors
openSUSE:Product highlights writing
tagline: From openSUSE
Contents |
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.
How Do We Write Product Highlights?
Writing the feature guide on your own would be an incredible amount of work. Seeing the size of it should probably already give that clue away, but let me repeat: it is a LOT of work. So, how do we write it? Together! By each taking on a small portion of the Feature Guide and Product Highlights, the job becomes much less daunting.
More specifically, the writing happens in three stages.
Gathering information
This phase starts during the milestones. As soon as feature freeze hits and packages have their final versions, we start looking at what has changed. We basically go through all the big, user-visible upgrades; first of course the desktops GNOME and Plasma Desktop, then apps like Gimp and Firefox, sever stuff like Apache, Samba and MySQL and admin or developer tools like wireshark or Anjuta. Starting with a smaller, familiar application is a good way to get started with a manageable topic.
For a package list, see for example Archive:Package_list_12.1 vs the latest on Package_list or a recent factory snapshot.
Also, we already collect what's coming in a few pages: openSUSE:Upcoming_features (more marketing focused) and openSUSE:Major_features (more technical).
It is crucial to not miss anything from the work we've done on openSUSE technologies - think YaST, zypper, snapper etcetera. Ask people on the -project and -factory lists to help filling in the blanks!
What Do We Need to Know?
The information that needs to be included is similar for most software.
- The name of the software and what it does
- what is included in that software - packages
- 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 stage, we need to go through the list of packages in the repositories, look at big, important stuff and if and how much it has changed. Look for references to anything new. We create a list of versions of important stuff in the document, grouping by key topics. 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.
Where Do I Find This Information?
The information on software is not found in openSUSE, but on the websites of the projects. You'll want to be a bit selective. Usually we are looking for major changes - not minor stuff. If GNOME has gone from 2.32.0 to 2.32.3 we're only talking about some bugfixes - not worth talking about. So check what we currently ship (do a zypper info [application] on your current system if you still run the old one or look in the repositories) and see what the relevant Feature Release is. Copy the release notes / list of new features into the document. (again, remember to link if you've copied something over!)
Have a look at previous feature guides: we need about a paragraph on major things and just a few items on less central pieces of openSUSE. So, a 300 entry changelog is not needed: usually, release announcements mention the major 3-5 things and that is usually enough.
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.
Writing Out the Formal Feature Guide
While phase one is being worked on (finding versions and copying over the feature info) some writers 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.
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: 2-3 is really a lot already. 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.