&title;

From owner-svn-doc-all@FreeBSD.ORG Fri Oct 25 20:03:38 2013 Return-Path: Delivered-To: svn-doc-all@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:1900:2254:206a::19:1]) (using TLSv1 with cipher ADH-AES256-SHA (256/256 bits)) (No client certificate requested) by hub.freebsd.org (Postfix) with ESMTP id BEA59FAF; Fri, 25 Oct 2013 20:03:38 +0000 (UTC) (envelope-from pgj@FreeBSD.org) Received: from svn.freebsd.org (svn.freebsd.org [IPv6:2001:1900:2254:2068::e6a:0]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mx1.freebsd.org (Postfix) with ESMTPS id A958E2E20; Fri, 25 Oct 2013 20:03:38 +0000 (UTC) Received: from svn.freebsd.org ([127.0.1.70]) by svn.freebsd.org (8.14.7/8.14.7) with ESMTP id r9PK3cHV011786; Fri, 25 Oct 2013 20:03:38 GMT (envelope-from pgj@svn.freebsd.org) Received: (from pgj@localhost) by svn.freebsd.org (8.14.7/8.14.5/Submit) id r9PK3bxP011780; Fri, 25 Oct 2013 20:03:37 GMT (envelope-from pgj@svn.freebsd.org) Message-Id: <201310252003.r9PK3bxP011780@svn.freebsd.org> From: Gabor Pali Date: Fri, 25 Oct 2013 20:03:37 +0000 (UTC) To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r43041 - head/en_US.ISO8859-1/htdocs/news/status X-SVN-Group: doc-head MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-BeenThere: svn-doc-all@freebsd.org X-Mailman-Version: 2.1.14 Precedence: list List-Id: "SVN commit messages for the entire doc trees $except for " user" , " projects" , and " translations" $" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Fri, 25 Oct 2013 20:03:38 -0000 Author: pgj Date: Fri Oct 25 20:03:37 2013 New Revision: 43041 URL: http://svnweb.freebsd.org/changeset/doc/43041 Log: - Add a "how to" page on writing quarterly status reports - Adjust the report sample to include the recommendations Submitted by: theraven Added: head/en_US.ISO8859-1/htdocs/news/status/howto.xml (contents, props changed) Modified: head/en_US.ISO8859-1/htdocs/news/status/Makefile head/en_US.ISO8859-1/htdocs/news/status/report-sample.xml head/en_US.ISO8859-1/htdocs/news/status/status.xml Modified: head/en_US.ISO8859-1/htdocs/news/status/Makefile ============================================================================== --- head/en_US.ISO8859-1/htdocs/news/status/Makefile Fri Oct 25 09:48:55 2013 (r43040) +++ head/en_US.ISO8859-1/htdocs/news/status/Makefile Fri Oct 25 20:03:37 2013 (r43041) @@ -7,7 +7,7 @@ .include "../Makefile.inc" .endif -DOCS= status.xml +DOCS= status.xml howto.xml XMLDOCS= report-2001-06 XMLDOCS+= report-2001-07 Added: head/en_US.ISO8859-1/htdocs/news/status/howto.xml ============================================================================== --- /dev/null 00:00:00 1970 (empty, because file is newly added) +++ head/en_US.ISO8859-1/htdocs/news/status/howto.xml Fri Oct 25 20:03:37 2013 (r43041) @@ -0,0 +1,105 @@ + + +]> + + + + &title; + $FreeBSD$ + + + + +

&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.

+ +

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 &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.

+ +

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 &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.

+ +

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)?

+ +

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.

+ +

Back to the main page

+ + Modified: head/en_US.ISO8859-1/htdocs/news/status/report-sample.xml ============================================================================== --- head/en_US.ISO8859-1/htdocs/news/status/report-sample.xml Fri Oct 25 09:48:55 2013 (r43040) +++ head/en_US.ISO8859-1/htdocs/news/status/report-sample.xml Fri Oct 25 20:03:37 2013 (r43041) @@ -11,13 +11,20 @@ + John - Smith test@FreeBSD.org + + + + Wunderteam + + team@FreeBSD.org + @@ -32,20 +39,23 @@ -

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.

+ +

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.

Just start another `p' tag.

What has happened since the last report? Let us know what is new + in this area.

- Some work you need help with - More work - Keep these short and to the point + If help is needed, make this explicit! + 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. - Modified: head/en_US.ISO8859-1/htdocs/news/status/status.xml ============================================================================== --- head/en_US.ISO8859-1/htdocs/news/status/status.xml Fri Oct 25 09:48:55 2013 (r43040) +++ head/en_US.ISO8859-1/htdocs/news/status/status.xml Fri Oct 25 20:03:37 2013 (r43041) @@ -42,6 +42,9 @@ If it is a new project, or if a project has not submitted any prior status reports, a short description may precede the status information.

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