How to Write FreeBSD Status Reports
FreeBSD status reports are published quarterly and provide the general public with a view of what is going on in the Project, and they are often augmented by special reports from Developer Summits. As they are one of our most visible forms of communication, they are very important. This page will provide some advice on writing status report entries from David Chisnall, experienced in technical writing.
Do not worry if you are not a native English speaker. The team handling status reports, [email protected], will check your entries for spelling and grammar, and fix it for you.
Introduce Your Work
Do not assume that the person reading the report knows about your project.
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. 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(4) 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 do not use any Yoyodyne products, you have communicated that FreeBSD's support for network devices is improving.
Show the Importance of Your Work
Status reports are not just about telling everyone that things were done, they also need to explain why they were done.
Carry on with 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? Status reports often say things like this:
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 have vaguely heard of whatever you have imported (especially into the ports tree: remember that there are over 20,000 other things there too...). List some of the new features, or bug fixes. Tell them why it is a good thing that we have the new version.
Tell Us Something New
Do not recycle the same status report items.
Bear in mind that status reports are not just reports on the status
of the project, they are reports on the change of status of the
project. If there is 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 been made since the
last report? What is left to do? When is it likely to be finished
(or, if finished
does not really apply, when is it likely to
be ready for wider use, for testing, for deployment in production,
and so on)?
Sponsorship
Do not forget about your sponsors.
If you or your project has received sponsorship, a scholarship from somebody or you have been already working as a contractor or an employee for a company, please include it. Sponsors always certainly appreciate if you thank them for their funding, but it is also beneficial for them to show that they are actively supporting the Project this way. Last, but not least, this helps FreeBSD to learn more about its important consumers.
Open Items
If help is needed, make this explicit!
Is there any help needed with something? 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 there is already enough people working on the project, or it is in a state where adding more people would not speed it up, then the latter is better. Give some big work items that are in progress, and maybe indicate who is focussing on each one.
List tasks, with enough detail that people know if they are likely to be able to do them, and invite people to get in contact.