os/doc
3
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

- Add a "how to" page on writing quarterly status reports

Browse source 
- Adjust the report sample to include the recommendations

Submitted by:	theraven
This commit is contained in:
Gabor Pali 2013-10-25 20:03:37 +00:00
parent e784d12453
commit f858b1340c
Notes: svn2git 2020-12-08 03:00:23 +00:00 
svn path=/head/; revision=43041
4 changed files with 130 additions and 12 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
en_US.ISO8859-1/htdocs/news/status/Makefile
View file

@ -7,7 +7,7 @@
.include "../Makefile.inc" .include "../Makefile.inc"
.endif .endif
DOCS= status.xml DOCS= status.xml howto.xml
XMLDOCS= report-2001-06 XMLDOCS= report-2001-06
XMLDOCS+= report-2001-07 XMLDOCS+= report-2001-07

105
en_US.ISO8859-1/htdocs/news/status/howto.xml Normal file
View file

@ -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>

32
en_US.ISO8859-1/htdocs/news/status/report-sample.xml
View file

@ -11,13 +11,20 @@
<contact> <contact>
<person> <person>
<name> <name>
<!-- For persons -->
<given>John</given> <given>John</given>
<common>Smith</common> <common>Smith</common>
</name> </name>
<email>test@FreeBSD.org</email> <email>test@FreeBSD.org</email>
</person> </person>
<!-- For teams or groups -->
<person>
<name>Wunderteam</name>
<email>team@FreeBSD.org</email>
</person>
</contact> </contact>
<!-- Optional section but highly encouraged. --> <!-- Optional section but highly encouraged. -->
@ -32,20 +39,23 @@
<!-- Required section. --> <!-- Required section. -->
<body> <body>
<p>You can start your first paragraph here. Generally speaking, you <!-- Do not worry if you are not a native English speaker. -->
will only usually submit one paragraph per status report, as they <p>Introduce your work. Do not assume that the person reading the
are intended to be somewhat brief. If, however, you find it report knows about your project.</p>
necessary to write one with multiple paragraphs, it's fairly
straightforward.</p>
<p>Just start another `p' tag.</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>What has happened since the last report? Let us know what is new
in this area.</p>
</body> </body>
<!-- Optional section for listing tasks. --> <!-- Optional section for listing tasks. -->
<help> <help>
<task>Some work you need help with</task> <task>If help is needed, make this explicit!</task>
<task>More work</task> <task>List tasks, with enough detail that people know if they are
<task>Keep these short and to the point</task> likely to be able to do them, and invite people to get in
contact.</task>
</help> </help>
</project> </project>

3
en_US.ISO8859-1/htdocs/news/status/status.xml
View file

@ -42,6 +42,9 @@
If it is a new project, or if a project has not submitted any prior status 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> 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 <p>Periodically special status reports are also prepared and
published. One of those are the developer summit reports. published. One of those are the developer summit reports.
Developer summits are places where developers meet in person to Developer summits are places where developers meet in person to