You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@community.apache.org by "rbowen (via GitHub)" <gi...@apache.org> on 2023/06/16 13:39:19 UTC

[PR] What makes a good report? (comdev-site)

rbowen opened a new pull request, #125:
URL: https://github.com/apache/comdev-site/pull/125

   Some advice on writing a *good* board report, rather than just checking the box.


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: dev-unsubscribe@community.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@community.apache.org
For additional commands, e-mail: dev-help@community.apache.org


Re: [PR] What makes a good report? (comdev-site)

Posted by Craig Russell <ap...@gmail.com>.

> On Jun 26, 2023, at 05:29, Rich Bowen <rb...@rcbowen.com> wrote:
> 
> In the past we have avoided linking to whimsy in public facing
> documentation. It encourages people to dig to find what they can find.
> Whimsy is *not* a place that we want people digging, IMHO, and if there's
> alternate (there is) we should use it.

I completely agree. The board minutes are published here:
https://apache.org/foundation/board/calendar.html

> 
> On Fri, Jun 23, 2023, 19:47 sebb <se...@gmail.com> wrote:
> 
>> On Sat, 24 Jun 2023 at 00:28, Rich Bowen <rb...@rcbowen.com> wrote:
>>> 
>>> On Fri, Jun 23, 2023, 06:10 rlenferink (via GitHub) <gi...@apache.org>
>> wrote:
>>> 
>>>> 
>>>> rlenferink commented on code in PR #125:
>>>> URL:
>> https://github.com/apache/comdev-site/pull/125#discussion_r1239637617
>>>> 
>>>> 
>>>> 
>>>> Review Comment:
>>>>   Great addition! Should we maybe link to
>>>> https://whimsy.apache.org/board/minutes/ if people want to easily
>> select
>>>> another project and have a look at their past reports ?
>>>> 
>>> 
>>> That's private but yeah I will link to the public version of that.
>> 
>> $ curl -I https://whimsy.apache.org/board/minutes/
>> HTTP/1.1 200 OK
>> 
>> Looks public to me ...
>> 
>>>> 
>> 
>> ---------------------------------------------------------------------
>> To unsubscribe, e-mail: dev-unsubscribe@community.apache.org
>> For additional commands, e-mail: dev-help@community.apache.org
>> 
>> 

Craig L Russell
clr@apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@community.apache.org
For additional commands, e-mail: dev-help@community.apache.org


Re: [PR] What makes a good report? (comdev-site)

Posted by Rich Bowen <rb...@rcbowen.com>.
In the past we have avoided linking to whimsy in public facing
documentation. It encourages people to dig to find what they can find.
Whimsy is *not* a place that we want people digging, IMHO, and if there's
alternate (there is) we should use it.

On Fri, Jun 23, 2023, 19:47 sebb <se...@gmail.com> wrote:

> On Sat, 24 Jun 2023 at 00:28, Rich Bowen <rb...@rcbowen.com> wrote:
> >
> > On Fri, Jun 23, 2023, 06:10 rlenferink (via GitHub) <gi...@apache.org>
> wrote:
> >
> > >
> > > rlenferink commented on code in PR #125:
> > > URL:
> https://github.com/apache/comdev-site/pull/125#discussion_r1239637617
> > >
> > >
> > >
> > > Review Comment:
> > >    Great addition! Should we maybe link to
> > > https://whimsy.apache.org/board/minutes/ if people want to easily
> select
> > > another project and have a look at their past reports ?
> > >
> >
> > That's private but yeah I will link to the public version of that.
>
> $ curl -I https://whimsy.apache.org/board/minutes/
> HTTP/1.1 200 OK
>
> Looks public to me ...
>
> > >
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@community.apache.org
> For additional commands, e-mail: dev-help@community.apache.org
>
>

Re: [PR] What makes a good report? (comdev-site)

Posted by sebb <se...@gmail.com>.
On Sat, 24 Jun 2023 at 00:28, Rich Bowen <rb...@rcbowen.com> wrote:
>
> On Fri, Jun 23, 2023, 06:10 rlenferink (via GitHub) <gi...@apache.org> wrote:
>
> >
> > rlenferink commented on code in PR #125:
> > URL: https://github.com/apache/comdev-site/pull/125#discussion_r1239637617
> >
> >
> >
> > Review Comment:
> >    Great addition! Should we maybe link to
> > https://whimsy.apache.org/board/minutes/ if people want to easily select
> > another project and have a look at their past reports ?
> >
>
> That's private but yeah I will link to the public version of that.

$ curl -I https://whimsy.apache.org/board/minutes/
HTTP/1.1 200 OK

Looks public to me ...

> >

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@community.apache.org
For additional commands, e-mail: dev-help@community.apache.org


Re: [PR] What makes a good report? (comdev-site)

Posted by Craig Russell <ap...@gmail.com>.

> On Jun 23, 2023, at 16:28, Rich Bowen <rb...@rcbowen.com> wrote:
> 
> On Fri, Jun 23, 2023, 06:10 rlenferink (via GitHub) <gi...@apache.org> wrote:
> 
>> 
>> rlenferink commented on code in PR #125:
>> URL: https://github.com/apache/comdev-site/pull/125#discussion_r1239637617
>> 
>> 
>> 
>> Review Comment:
>>   Great addition! Should we maybe link to
>> https://whimsy.apache.org/board/minutes/ if people want to easily select
>> another project and have a look at their past reports ?
>> 
> 
> That's private but yeah I will link to the public version of that.

The board agenda is private, including director comments and sections of reports marked with </private/> flags. 

The secretary creates a subset of the agenda which becomes the minutes, which after approval by the board are published to the public.

Craig

> 
>> 

Craig L Russell
clr@apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@community.apache.org
For additional commands, e-mail: dev-help@community.apache.org


Re: [PR] What makes a good report? (comdev-site)

Posted by Rich Bowen <rb...@rcbowen.com>.
On Fri, Jun 23, 2023, 06:10 rlenferink (via GitHub) <gi...@apache.org> wrote:

>
> rlenferink commented on code in PR #125:
> URL: https://github.com/apache/comdev-site/pull/125#discussion_r1239637617
>
>
>
> Review Comment:
>    Great addition! Should we maybe link to
> https://whimsy.apache.org/board/minutes/ if people want to easily select
> another project and have a look at their past reports ?
>

That's private but yeah I will link to the public version of that.

>

Re: [PR] What makes a good report? (comdev-site)

Posted by "rbowen (via GitHub)" <gi...@apache.org>.
rbowen commented on PR #125:
URL: https://github.com/apache/comdev-site/pull/125#issuecomment-1600266000

   Thanks, @sebbASF , changes made.


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: dev-unsubscribe@community.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@community.apache.org
For additional commands, e-mail: dev-help@community.apache.org


Re: [PR] What makes a good report? (comdev-site)

Posted by "rbowen (via GitHub)" <gi...@apache.org>.
rbowen merged PR #125:
URL: https://github.com/apache/comdev-site/pull/125


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: dev-unsubscribe@community.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@community.apache.org
For additional commands, e-mail: dev-help@community.apache.org


Re: [PR] What makes a good report? (comdev-site)

Posted by "psteitz (via GitHub)" <gi...@apache.org>.
psteitz commented on PR #125:
URL: https://github.com/apache/comdev-site/pull/125#issuecomment-1608391078

   This is really nice work.  On first read, I though there were things missing re challenges, but everything is there.  I guess people who know how to write know how to write :)
   
   Re Bertrand's excellent suggestion of including links to good reports and explaining why, I kind of tried to do that for a year or so in my Chairman's reports.  So there may be some examples or at least some inspiration there.  See, e.g. https://svn.apache.org/repos/private/foundation/board/archived_agendas/board_agenda_2018_04_18.txt
   
   That is all old stuff, but the same kind of approach could be taken with newer reports.  Maybe even just using some of the ones I called out might work.


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: dev-unsubscribe@community.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@community.apache.org
For additional commands, e-mail: dev-help@community.apache.org


Re: [PR] What makes a good report? (comdev-site)

Posted by "rbowen (via GitHub)" <gi...@apache.org>.
rbowen commented on code in PR #125:
URL: https://github.com/apache/comdev-site/pull/125#discussion_r1236447269


##########
source/pmc/reporting.md:
##########
@@ -52,3 +52,42 @@ tool](https://whimsy.apache.org/board/agenda), or committed directly to
 the [subversion
 repository](https://svn.apache.org/repos/private/foundation/board).
 
+## What makes a good report
+
+As with anything you write, the most important thing to keep in mind
+when writing your board report is who your audience is.
+
+The primary audience of your report is, of course, the board of
+directors. They are not experts on your particular technology. They are,
+rather, interested in the health and sustainability of the project.
+Questions to consider include:
+
+* Do you have enough active participants - both committers and PMC members -
+  to respond to urgent bugs or security?
+* Have you responded to any questions or comments that the board made on
+  your previous report?
+* Have you pointed out major achievements, or challenges, encountered in
+  the past quarter that an outsider would have missed?
+
+The secondary audience of your report is the general public. The minutes
+of board meetings are
+[published](https://apache.org/foundation/board/calendar.html) for our users,
+sponsors, the press, and the general public to read. Consider that
+audience when writing. For example, if there's a story that you'd like
+the press to tell about your project, you might mention it, and provide
+a quote that you'd like to see in an article.
+
+If there's something you wish to bring to the attention of the board,
+but isn't for public consumption, enclose it in &lt;private&gt; tags so
+that it won't be published in the public minutes.
+
+The report isn't just a once-a-quarter box to check -- It's your 

Review Comment:
   Thanks Sebb. Changes made.



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: dev-unsubscribe@community.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@community.apache.org
For additional commands, e-mail: dev-help@community.apache.org


Re: [PR] What makes a good report? (comdev-site)

Posted by "bdelacretaz (via GitHub)" <gi...@apache.org>.
bdelacretaz commented on PR #125:
URL: https://github.com/apache/comdev-site/pull/125#issuecomment-1596677513

   Great stuff, thanks! It might be useful to include links to reports that we find good, and explain why.


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: dev-unsubscribe@community.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@community.apache.org
For additional commands, e-mail: dev-help@community.apache.org


Re: [PR] What makes a good report? (comdev-site)

Posted by "sebbASF (via GitHub)" <gi...@apache.org>.
sebbASF commented on code in PR #125:
URL: https://github.com/apache/comdev-site/pull/125#discussion_r1233708999


##########
source/pmc/reporting.md:
##########
@@ -52,3 +52,42 @@ tool](https://whimsy.apache.org/board/agenda), or committed directly to
 the [subversion
 repository](https://svn.apache.org/repos/private/foundation/board).
 
+## What makes a good report

Review Comment:
   good report => good board report



##########
source/pmc/reporting.md:
##########
@@ -52,3 +52,42 @@ tool](https://whimsy.apache.org/board/agenda), or committed directly to
 the [subversion
 repository](https://svn.apache.org/repos/private/foundation/board).
 
+## What makes a good report
+
+As with anything you write, the most important thing to keep in mind
+when writing your board report is who your audience is.
+
+The primary audience of your report is, of course, the board of
+directors. They are not experts on your particular technology. They are,

Review Comment:
   not experts => not generally experts ?



##########
source/pmc/reporting.md:
##########
@@ -52,3 +52,42 @@ tool](https://whimsy.apache.org/board/agenda), or committed directly to
 the [subversion
 repository](https://svn.apache.org/repos/private/foundation/board).
 
+## What makes a good report
+
+As with anything you write, the most important thing to keep in mind
+when writing your board report is who your audience is.
+
+The primary audience of your report is, of course, the board of
+directors. They are not experts on your particular technology. They are,
+rather, interested in the health and sustainability of the project.
+Questions to consider include:
+
+* Do you have enough active participants - both committers and PMC members -
+  to respond to urgent bugs or security?
+* Have you responded to any questions or comments that the board made on
+  your previous report?
+* Have you pointed out major achievements, or challenges, encountered in
+  the past quarter that an outsider would have missed?
+
+The secondary audience of your report is the general public. The minutes
+of board meetings are
+[published](https://apache.org/foundation/board/calendar.html) for our users,
+sponsors, the press, and the general public to read. Consider that
+audience when writing. For example, if there's a story that you'd like
+the press to tell about your project, you might mention it, and provide
+a quote that you'd like to see in an article.
+
+If there's something you wish to bring to the attention of the board,
+but isn't for public consumption, enclose it in &lt;private&gt; tags so
+that it won't be published in the public minutes.
+
+The report isn't just a once-a-quarter box to check -- It's your 

Review Comment:
   It’s => it’s



##########
source/pmc/reporting.md:
##########
@@ -52,3 +52,42 @@ tool](https://whimsy.apache.org/board/agenda), or committed directly to
 the [subversion
 repository](https://svn.apache.org/repos/private/foundation/board).
 
+## What makes a good report
+
+As with anything you write, the most important thing to keep in mind
+when writing your board report is who your audience is.
+
+The primary audience of your report is, of course, the board of
+directors. They are not experts on your particular technology. They are,
+rather, interested in the health and sustainability of the project.
+Questions to consider include:
+
+* Do you have enough active participants - both committers and PMC members -
+  to respond to urgent bugs or security?
+* Have you responded to any questions or comments that the board made on
+  your previous report?
+* Have you pointed out major achievements, or challenges, encountered in
+  the past quarter that an outsider would have missed?
+
+The secondary audience of your report is the general public. The minutes
+of board meetings are
+[published](https://apache.org/foundation/board/calendar.html) for our users,
+sponsors, the press, and the general public to read. Consider that
+audience when writing. For example, if there's a story that you'd like
+the press to tell about your project, you might mention it, and provide
+a quote that you'd like to see in an article.
+
+If there's something you wish to bring to the attention of the board,
+but isn't for public consumption, enclose it in &lt;private&gt; tags so

Review Comment:
   It’s perhaps not obvious that the second tag should be &lt;/private&gt;



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: dev-unsubscribe@community.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@community.apache.org
For additional commands, e-mail: dev-help@community.apache.org


Re: [PR] What makes a good report? (comdev-site)

Posted by "rbowen (via GitHub)" <gi...@apache.org>.
rbowen commented on PR #125:
URL: https://github.com/apache/comdev-site/pull/125#issuecomment-1600265825

   @bdelacretaz It is my intent to add some references to "good" reports, and have been reading past minutes to find some good examples.


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: dev-unsubscribe@community.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@community.apache.org
For additional commands, e-mail: dev-help@community.apache.org


Re: [PR] What makes a good report? (comdev-site)

Posted by "rlenferink (via GitHub)" <gi...@apache.org>.
rlenferink commented on code in PR #125:
URL: https://github.com/apache/comdev-site/pull/125#discussion_r1239637617


##########
source/pmc/reporting.md:
##########
@@ -52,3 +52,50 @@ tool](https://whimsy.apache.org/board/agenda), or committed directly to
 the [subversion
 repository](https://svn.apache.org/repos/private/foundation/board).
 
+## What makes a good board report
+
+As with anything you write, the most important thing to keep in mind
+when writing your board report is who your audience is.
+
+The primary audience of your report is, of course, the board of
+directors. They are not, generally, experts on your particular technology. They are,
+rather, interested in the health and sustainability of the project.
+Questions to consider include:
+
+* Do you have enough active participants - both committers and PMC members -
+  to respond to urgent bugs or security?
+* Have you responded to any questions or comments that the board made on
+  your previous report?
+* Have you pointed out major achievements, or challenges, encountered in
+  the past quarter that an outsider would have missed?
+
+The secondary audience of your report is the general public. The minutes
+of board meetings are
+[published](https://apache.org/foundation/board/calendar.html) for our users,
+sponsors, the press, and the general public to read. Consider that
+audience when writing. For example, if there's a story that you'd like
+the press to tell about your project, you might mention it, and provide
+a quote that you'd like to see in an article.
+
+If there's something you wish to bring to the attention of the board,
+but isn't for public consumption, enclose it in &lt;private&gt; tags so
+that it won't be published in the public minutes.
+
+For example:
+
+```
+<private>
+Private tags should be alone on a line
+</private>
+```
+
+The report isn't just a once-a-quarter box to check -- it's your 
+opportunity to tell the story of your project,
+celebrate your accomplishments, ask for help or advice on challenges
+you're facing, and identify places where new contributors might find
+something to work on.
+
+We encourage you to look at [past board
+reports](https://apache.org/foundation/board/calendar.html) for inspiration from
+other projects' reports. 

Review Comment:
   Great addition! Should we maybe link to https://whimsy.apache.org/board/minutes/ if people want to easily select another project and have a look at their past reports ?



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: dev-unsubscribe@community.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@community.apache.org
For additional commands, e-mail: dev-help@community.apache.org