&os; 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, monthly@FreeBSD.org, will check + your entries for spelling and grammar, and fix it for you.
+ +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 &os; web site and are one of the first + things that people will read if they want to know a bit about what + &os; 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 + &os;'s support for network devices is improving.
+ +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 &os; 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 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.
+ +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)?
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.
+ + + + diff --git a/en_US.ISO8859-1/htdocs/news/status/report-sample.xml b/en_US.ISO8859-1/htdocs/news/status/report-sample.xml index d37d9c3651..a4b0229af6 100644 --- a/en_US.ISO8859-1/htdocs/news/status/report-sample.xml +++ b/en_US.ISO8859-1/htdocs/news/status/report-sample.xml @@ -11,13 +11,20 @@You can start your first paragraph here. Generally speaking, you - will only usually submit one paragraph per status report, as they - are intended to be somewhat brief. If, however, you find it - necessary to write one with multiple paragraphs, it's fairly - straightforward.
+ +Introduce your work. Do not assume that the person reading the + report knows about your project.
-Just start another `p' tag.
+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.
+ +What has happened since the last report? Let us know what is new + in this area.
For more exact guidelines on how to write good status reports, + please consult our recommendations.
+Periodically special status reports are also prepared and published. One of those are the developer summit reports. Developer summits are places where developers meet in person to