svn commit: r43041 - head/en_US.ISO8859-1/htdocs/news/status
Gabor Pali
pgj at FreeBSD.org
Fri Oct 25 20:03:38 UTC 2013
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 at 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 at 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 at FreeBSD.org</email>
</person>
+
+ <!-- For teams or groups -->
+ <person>
+ <name>Wunderteam</name>
+
+ <email>team at 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 to
More information about the svn-doc-all
mailing list