- Update documentation on how to prepare the quarterly status reports

svn path=/head/; revision=44117

en_US.ISO8859-1/htdocs/news/status/README

@@ -11,17 +11,25 @@ Compiling status reports - best practices
     writing.  Make sure to keep them up to date with regard to categories
     to pick from and place them prominently in the CFR - otherwise people
     submit plain text reports and you have to format them yourself.
+  - Reporting howto is at: http://www.freebsd.org/news/status/howto.html.
+    It contains a great deal of useful hints for the submitters on how
+    to write good reports.  But it also helps to forward all the completed
+    reports to developers for reference, and point to the latest report
+    in the CFR.
 
 2) In the past we usually had to extend the deadline by a week in order to
    get everybody to report.  Starting early with kind reminders seems to
-   help ;)
+   help ;)  Ideally, reminders should be sent at least one month before the
+   deadline.  But it is worthwhile the keep sending reminders two weeks
+   before the deadline and on the day of the deadline.
 
 3) The following groups should be definitely approached for a report on
    their recent activities:
    - core@, portmgr@, doceng@, secteam@, re@, postmaster@, clusteradm@,
      devsummit@ (team reports).
    - FreeBSD Foundation (emaste@), participants of Foundation-sponsored
-     projects.
+     projects, deb@ (Deb Goodkin) can also do a report for the Foundation
+     itself.
    - Various conference organizers, depending on the season:
      - BSDCan (info@bsdcan.org) May (April-June)
      - EuroBSDcon (foundation@eurobsdcon.org) Sept-Oct (October-December)
@@ -35,10 +43,19 @@ Compiling status reports - best practices
    if at all possible.
 
 4) Building the report:
-  - Accumulate the received reports in a single .xml file and use tidy(1) to
-    get them well-formatted.  Usually <url>s without a description are missing
-    the closing "/>" which is the cause for most of the errors you will
-    encounter.  Sometimes other closing tags are missing.
+  - Fold the reports into a work-in-progress draft as they are coming in (see
+    point 5) for putting the report together). Commit the result and hook the
+    draft into the build, so you can (almost) immediately provide the
+    submitters a preview of their entries.  This is also a good excuse to do
+    a acknowledgement on the receipt.
+  - While the report draft is kept updated, other doc-committers (wblock,
+    pluknet, and bjk, for example) may review the individual entries and
+    propose fixes.
+  - As mentioned above, the received reports should be in a single .xml file,
+    where tidy(1) may be used to get them well-formatted.  Usually <url>s
+    without a description are missing the closing "/>" which is the cause for
+    most of the errors you will encounter.  Sometimes other closing tags are
+    missing.
   - Invoking tidy with the following options seems to cause the fewest
     problems: tidy -xml -i -wrap 74 -latin1 -preserve
   - Some special characters still break with that - noticed when sos@
@@ -54,13 +71,8 @@ Compiling status reports - best practices
         <li>some item</li>
       </ul>
       <p>Some more blabla ...
-  - Review and commit the reports immediately as they are coming in.  Hook the
-    resulting XML to the build for the first time but do not link to it from
-    anywhere.  This gives time for other committers to review and suggest
-    minor changes.
 
-5) After a couple of iterations of the above, wrap the whole thing in a
-   report template:
+5) Wrapping the whole thing in a report template:
 
 <?xml version="1.0" encoding="iso-8859-1" ?>
 <!DOCTYPE report PUBLIC "-//FreeBSD//DTD FreeBSD XML Database for Status
@@ -144,17 +156,17 @@ Report//EN"
   </category>
 </report>
 
-   Categories are subject to change obviously.  They come out in the order
+ - Categories are subject to change obviously.  They come out in the order
    as stated in the report.  After another round of tidy(1) try to balance
    the categories.  Put things where they belong best, retire categories
    that don't fill up, etc.  Adding it to your local build and looking at
    the html helps.  Make sure you have an up-to-date doc tree.
 
+ - theraven may be poked for composing a nice introduction for the reports.
+   But should be usually the last step in the process; a good introduction
+   can be only written once the report is considered finished.
+
 6) Sending it out:
-  - Explicitly mail all the submitters (in BCC:) with the link pointing to
-    the HTML version of the prepared report so they could check their
-    entries before publication.  It is wise to set an exact deadline for
-    this, in order to avoid late comments.
   - After a few days, collate and commit the changes.  Also update the
     next due date in status.xml and link to the new report.
   - Add a news entry to head/share/xml/news.xml.  Template:
@@ -167,8 +179,8 @@ Report//EN"
         </event>
   - Extract a text version with the command
     lynx -dump -nolist report.html > report.txt and prettify it.
-  - Send out To: hackers, CC: current, stable.  New email to: announce@.
-    This needs to be approved, so find someone who can do that before you
-    start.
+  - Send out To: hackers, CC: current, stable, BCC: developers.  New email
+    to: announce@.  This last one needs to be approved, so find someone
+    (mail postmaster) who can do that before you start.
 
 7) Repeat.