Date: Fri, 25 Oct 2013 20:03:37 +0000 (UTC) From: Gabor Pali <pgj@FreeBSD.org> 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 Message-ID: <201310252003.r9PK3bxP011780@svn.freebsd.org>
index | next in thread | raw e-mail
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 @@ +<?xml version="1.0" encoding="iso-8859-1"?> +<!DOCTYPE html PUBLIC "-//FreeBSD//DTD XHTML 1.0 Transitional-Based Extension//EN" +"http://www.FreeBSD.org/XML/doc/share/xml/xhtml10-freebsd.dtd" [ +<!ENTITY title "How to Write FreeBSD Status Reports"> +]> + +<html xmlns="http://www.w3.org/1999/xhtml">; + <head> + <title>&title;</title> + <cvs:keyword xmlns:cvs="http://www.FreeBSD.org/XML/CVS">$FreeBSD$</cvs:keyword>; + </head> + + <body class="navinclude.about"> + + <p>&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 <a href="mailto:theraven@FreeBSD.org">David + Chisnall</a>, experienced in technical writing.</p> + + <p><em>Do not worry if you are not a native English speaker. The team + handling status reports, <tt>monthly@FreeBSD.org</tt>, will check + your entries for spelling and grammar, and fix it for you.</em></p> + + <h2>Introduce Your Work</h2> + + <p><em>Do not assume that the person reading the report knows about + your project.</em></p> + + <p>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:</p> + + <pre>abc(4) support was added, including frobnicator compatibility.</pre> + + <p>Someone reading this, if they are familiar with UNIX man pages, + will know that <tt>abc(4)</tt> is some kind of device. But why should + the reader care? What kind of device is it? Compare with this + version:</p> + + <pre>A new driver, abc(4), was added to the tree, bringing support for +Yoyodyne's range Frobnicator of network interfaces.</pre> + + <p>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.</p> + + <h2>Show the Importance of Your Work</h2> + + <p><em>Status reports are not just about telling everyone that things + were done, they also need to explain why they were done.</em></p> + + <p>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:</p> + + <pre>We imported Cyberdyne Systems T800 into the tree.</pre> + + <p>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.</p> + + <h2>Tell Us Something New</h2> + + <p><em>Do not recycle the same status report items.</em></p> + + <p>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 <q>finished</q> does not really apply, when is it likely to + be ready for wider use, for testing, for deployment in production, + and so on)?</p> + + <h2>Open Items</h2> + + <p><em>If help is needed, make this explicit!</em></p> + + <p>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.</p> + + <p>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.</p> + + <p><a href="status.html">Back to the main page</a></p> + </body> +</html> 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 @@ <contact> <person> <name> + <!-- For persons --> <given>John</given> - <common>Smith</common> </name> <email>test@FreeBSD.org</email> </person> + + <!-- For teams or groups --> + <person> + <name>Wunderteam</name> + + <email>team@FreeBSD.org</email> + </person> </contact> <!-- Optional section but highly encouraged. --> @@ -32,20 +39,23 @@ <!-- Required section. --> <body> - <p>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.</p> + <!-- Do not worry if you are not a native English speaker. --> + <p>Introduce your work. Do not assume that the person reading the + report knows about your project.</p> + + <p>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.</p> - <p>Just start another `p' tag.</p> + <p>What has happened since the last report? Let us know what is new + in this area.</p> </body> <!-- Optional section for listing tasks. --> <help> - <task>Some work you need help with</task> - <task>More work</task> - <task>Keep these short and to the point</task> + <task>If help is needed, make this explicit!</task> + <task>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.</task> </help> - </project> 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.</p> + <p>For more exact guidelines on how to write good status reports, + please consult <a href="howto.html">our recommendations</a>.</p> + <p>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 tohome | help
Want to link to this message? Use this
URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201310252003.r9PK3bxP011780>