Mail pertaining to Software Documentation Reviews 2007

To Combined Performance WG Convenors

Ian has already agreed to reviews. Mail to be checked by Maria and then sent by her, cc Ian and Karl.

Dear Combined Performance Working Group Convernors

Over the Summer and early Autumn of 2007, we are proposing to hold Reviews of the Documentation corresponding to the various Computing Domains. This will look at the Doxygen documentation of C++ and Python, as well as supporting Web (TWiki) pages (but not the actual code). In discussion with Ian, we considered it would be a good idea to include the code of the Combined Performance WGs in this. This has been discussed in the CMB/SPMB, but so far has not been brought to your attention.

The arrangements for this are still being finalised, but the current state of planning can be found on the TWiki page: DocumentationManagementReviews07. The first key step will be a "Documentation Standdown" between 28 May and 1 Jun - during this time, you are encouraged to work on your documentation. In this period, only tags associated with documentation will be accepted. Before you panic (because we are well aware that you are very busy), we expect that the reviews for the Combined Performance Groups won't be until September or October. So there will be plenty of time after the Standdown for additional improvements.

Further communications will follow. We hope this will be OK for your group. If you have any questions, do not hesitate to contact Stephen Haywood.

Best wishes - Stephen Haywood and Marian Smizanska

To Software Developers and All Combined Performance Groups

1st public announcement of Reviews. Mail to be checked by David, Fred and Maria, then Fabiola. Stephen to send, cc Dario, Stephen, Ian and Karl

Lists:

• hn-atlas-offlineSWDevelopment@cernNOSPAMPLEASE.ch
• atlas-egamma
• atlas-flavour-tagging (restricted)
• atlas-jets-combined
• hn-atlas-tauWG
• hn-atlas-MuonCombinedPerfWG@cernNOSPAMPLEASE.ch

Dear Software Developers and Combined Performance WG Members

Over the Summer of 2007, we are proposing to hold Reviews of the Documentation corresponding to the various Computing Domains, including the Combined Performance WGs. This will look at the Doxygen documentation of C++ and Python, as well as supporting Web (TWiki) pages (but not the actual code).

The arrangements for this are still being finalised, but the current state of planning can be found on the TWiki page: DocumentationManagementReviews07. The first key step will be a "Documentation Standdown" between 28 May and 1 Jun - during this time, you are encouraged to work on your documentation. In this period, only tags associated with documentation will be accepted.

We are in conctact with the Coordinators for the various activities, so we hope they will take the lead with this work. If you have any questions, do not hesitate to contact Stephen Haywood.

Best wishes - Fabiola Gianotti, David Quarrie, Fred Luehring and Stephen Haywood

To Computing Domain Leaders, Domain Documentation Contacts and Combined Performance WG Convenors

Confirming details with Coordinators. To be posted once preliminary dates are decided. Mail to be checked by David, Fred, Steve and Maria, then Stephen to send

Dear All

We are trying to firm up details for the Software Documentation Reviews. I would ask the Domain Leaders to take a look at DocumentationManagementReviews07.

1. Please check the proposed Dates and let me know if there are significant problems. (We are not sure quite how well the process will work, and so may need to adjust dates for Sep/Oct in the light of experience.)
2. Please check the list of Contacts for Documentation - this includes the names which the Computing Domains gave me some months ago. Let me know if key people are missing.
3. To form the Review Teams, we would like each Domain to nominate two people from the Domain to be Reviewers for other Domains (presumably taken from the list of Contacts, and possible needing additions).
4. We need one person (or two) for each Domain who will certify pages (see DocumentationManagementCertification). I assume these will be the Leaders/Coordinators of the Domains/WGs. Please see the proposed list for authorised DocumentationManagementCertifiers. Please edit this page correcting any mistakes and inserting CERN AFS account names.

PLEASE respond promptly to this mail so that I don't have to chase you. I hope this is OK for you. Apologies to Combined Performance WG Convenors, as we have suddenly sprung this on you ... however, we would not propose to review your documentation until September/October, so you have bags of time to get things up to scratch.

Best wishes - Stephen Haywood

To Markus Elsing

To be sent in conjunction with previous mail.

Hi Markus

We have scheduled the review of the InDet Software Documentation first, since we believe it is one of the best documented Domains. There are quite some uncertainties as to how the Reviews will work and so we felt it best to start with one which we hope will generate fewer concerns and give us good examples of how things should be done. To aid in the learning process, I propose a slighthly enlarged Review Team.

I hope this is OK. Furthermore, I would welcome any suggestions you have (on top of those which are already proposed for Doxygen and TWiki) for what we should be looking for. This first Review will be somewhat exploratory and it will be a chance for you to educate some of us.

Cheers - Stephen

-- StephenHaywood - 25 Apr 2007