Disclaimer : This document is a work in progress and should not be considered official yet.

Announcement Guide

Joshua Nichols Author

Updated March 1, 2008

1. Creating announcements

To start, you'll need to go through all the setup you would need to do other documentation. This is already well documented here.

Announcements live in xml/htdocs/news/, relative to the root of the 'gentoo' CVS module. To create a new announcement, just create a new XML file in this directory. Typically, this is of the form YYYYmmdd-some-title-here.xml.

The order of announcements is determined by the contents of /dyn/news-index.xml. This file gets generated by a cron job, which does something like ls -r. This means that something like ZZ.xml would always show up first.

If you want to publish several items on the same day with a specific order, add an extra letter to the data, like 20080211a-foo.xml and 20080211b-bar.xml (the latter will appear above the former).

File format

Announcements are of a variation of your typical GuideXML.

Best to teach by example, so here's a basic one:

Code Listing 1.1: Announcement example

<?xml version='1.0'?>
<!DOCTYPE news SYSTEM "/dtd/guide.dtd">
<news gentoo="yes" category="linux">
  <poster>your_nick_here</poster>
  <date>YYYY-mm-dd</date>
  <title>First post!</title>
  <body>
    <p>
      Here there be content!
    </p>
  </body>
</news>

Here's what's really important:

Gentoo equals very yes
Category should be specified. Eventually XSL uses this to generate an image tag for the announcement. Some valid categories include:
- gentoo
- kde
- main
- linux
- moo
- plans
Poster... that's you, the one writing the announcement
Date of the announcement
Full title of the announcement
Body of the announcement. You can use the same XML you would be able to in an body tag for GuideXML

Discussion link

The announcement should contain a link to discuss it on the forums. Regretfully, this not automated so you will need to create a thread before posting the announcement.

You'd add a snippet like so:

Code Listing 1.2: Discussion link

<p>
  <uri link="http://forums.gentoo.org/viewtopic-t-657125.html">Discuss this!</uri>
</p>

2. Writing effective announcements

Now that you have the basics of creating an announcement, we can focus on writing effective announcements.

Certainly, at the most basic level we want to inform our audience of something. We also want to make it easy to understand what we're trying to say. We want to explain things in a way that they see why they should care about the announcement. And lastly, we want to engage the audience. Community has always been an important part of Gentoo, and we hope that well-written, timely announcements can help maintain and improve our sense of community.

Tips

Bold key words and phrases.
Avoid over-emphasizing unimportant thing. Doing so takes away from things that are important.
- Example: including specific dates. For things in the recent past, does it matter which day it specifically happened?
Be specific about what you are talking about, and avoid ambiguity
- Before: "Here are some stats before and after removing the digest files"
- After: "Here are some stats showing the size of the tree before and after removing the digest files"
Avoid overly long paragraphs.
Prefer simple language and sentence structure.
Use bullet points and tables when appropriate. It is a lot easier to read a list of bullet point list, than an equivalent sentence.
Speak directly to the user.
- Use "You" instead of "a user"
- Trying to have a conversation with the audience
- This is supported by having a forum thread go along with an announcement
Include relevant links whenever possible. Try to integrate them into the text, and avoid having 'here' links.
If that's not possible, list references at the end.
- List items most relevant to the user first
- Use appropriate text to encourage the user to want to read the reference
  - Explain why the user should care
  - Before: "DevManual entry on Digest and Manifest"
  - After: "Understanding digest and manifest files"
Explanations are key.
- Think about every word or concept you use. Try to anticipate what the audience might not be familar with.
- This is crucial if you want your announcements to be valuable to the audience.

Appropriate topics for announcements

This is by no means an exhaustive list, but intended to give you some ideas what could be announcement material.

Release related news
Significant user-affecting changes
GMN releases
Gentoo sponsored events, like booths at conferences
Gentoo related events, like user organized gatherings

References