How to Write a Status Report

FreeBSD status reports are published quarterly and provide the general public with a view of what's going on in the project. They're augmented by special reports from DevSummits. As they are one of our most visible forms of communication, they are very important. This page will provide some advice for people writing status report entries.

Don't worry if you are not a native English speaker. The status reports team will check your entries for spelling / grammar.

Introduce your work

The status reports have a wide distribution. They are often one of the top news items on the FreeBSD web site and are one of the first things that people will read if they want to know a bit about what FreeBSD is. Do not assume that the person reading the report knows about your project. Consider this example:

abc(4) support was added, including frobnicator compatibility

Someone reading this, if they are familiar with UNIX man pages, will know that abc is some kind of device. But why should the reader care? What kind of device is it? Compare with this version:

A new driver, abc(4), was added to the tree, bringing support for Yoyodyne's range Frobnicator of network interfaces.

Now the reader knows that abc is a network interface driver. Even if they don't use any Yoyodyne products, you've communicated that FreeBSD's support for network devices is improving.

Why should I care?

Status reports are not just about telling everyone that things were done, they also need to explain why they were done. Take the previous example. Why is it interesting that we now support Yoyodyne Frobnicator cards? Are they widespread? Are they used in a specific popular device? Are they used in a particular niche where FreeBSD has (or would like to have) a presence? Are they the fastest network cards on the planet? Lots of status reports say things like:

We imported Cyberdyne Systems T800 into the tree

And then they stop. Maybe the reader is an avid Cyberdyne fan and knows what exciting new features the T800 brings. This is unlikely. It is far more likely that they've vaguely heard of whatever you've imported (especially into the ports tree: remember that there are more than 24K other things there too...). List some of the new features, or bug fixes. Tell them why it's a good thing that we have the new version.

Tell me something new

Don't recycle the same status report items. They are not just reports on the status of the project, they are reports on the change of status of the project. If there's an ongoing project, spend a couple of sentences introducing it, but then spend the rest of the report talking about the new work. What progress have you made since the last report? What's left to do? When is it likely to be finished (or, if 'finished' doesn't really apply, when is it likely to be ready for wider use, for testing, for deployment in production, and so on)?

Open items

Do you want help with this? Are there tasks other people can do? There are two ways in which you can use the open items part of the status report: to solicit help, or to give a quick overview of the amount of work left. If you already have enough people working on the project, or it's in a state where adding more people wouldn't speed it up, then the latter is better. Give some big work items that you're doing, and maybe indicate who is focussing on each one.

If you want help, make this explicit! List tasks, with enough detail that people know if they're likely to be able to do them, and invite people to get in contact with you.

HowToWriteAStatusReport (last edited 2013-11-23 04:39:51 by MarkLinimon)