Re: [Rodin-handbook] Rodin Handbook - Review for the third iteration

SourceForge Headquarters 225 Broadway Suite 1600 San Diego, CA 92101 +1 (858) 454-5900

Dear all,

This is just a friendly reminder that we are currently in the review
phase of the third iteration of the Rodin Handbook project.  You still
have time until January 2nd to provide feedback that will influence the
work packages of the fourth iteration.

So... if you are still looking for inspiring reading material for the
holiday season, grab yourself a copy of the Handbook (okay, just kidding).

Happy holidays, and best wishes from the Rodin Handbook team,

- Michael

On 12/08/2011 01:53 PM, Michael Jastram wrote:
> Dear all,
>
> We just finished the third iteration (out of four) on the handbook and
> would like to invite you to the review.  As we usually allocate two
> weeks for the iteration review, and as the holidays are coming up, we
> will have a slightly longer review period.  We will begin with the
> forth and last iteration on January 2nd.  However, we would really
> appreciate feedback sooner, to allow us to react to your comments.  So
> please respond before the holidays (and please respond to the handbook
> mailing list for discussion).
>
> You can access our work so far at handbook.event-b.org
> <http://handbook.event-b.org>.  Note that we will continue to work on
> the handbook during the review phase.  Therefore, you will find two
> versions on that page: A "frozen" version for the review, and the
> latest build.  For the review, please make sure that you access the
> frozen build.
>
> The third iteration consists of six work packages
> <http://wiki.event-b.org/index.php/Documentation_Overhaul_DoW>, which
> are documented on the Rodin Wiki.  Links to all deliverables can be
> found on that page.  They are:
>
>   * WP3-1: Completion of the Reference Section
>   * WP3-2: User Tests of Tutorial
>   * WP3-3: Completion of the Tutorial
>   * WP3-4: Provide context to give the documentation a whole appearance
>   * WP3-5: Remove migrated content from Wiki
>   * WP3-6: Creation of an index
>   * WP3-7: Iteration Review
>
>
>     User Feedback
>
> So far, we got 98 pieces of feedback, most of them through the
> feedback form.  We also received feedback via email and the survey
> form, and we transcribed those issues to the form, so that we had one
> single repository to work from.  All but 4 entries got resolved (the
> remaining ones will be dealt with in the next iteration).
>
> In addition, we ran a survey that was specifically targeted at
> students taking a B block course in Düsseldorf.  These students
> learned for a week about B (but not Event-B, and not Rodin).  They
> then had to complete an assignment in Event-B, with the handbook
> provided as the reference text.  Five Students completed the
> assignment.  We distributed the survey on the Rodin and Deploy mailing
> lists as well, and we received seven responses in total.  Here is the
> Survey Result
> <http://handbook.event-b.org/review-3/2011_12_08_Handbook_Survey.pdf>.  The
> main take-aways are:
>
>   * The "General impression" of the handbook received 4.0 out of 5
>     (Question 6).  Readers were very happy with the structure (4.6)
>     and the text style (4.9).  We believe that especially the last is
>     due to the terrific work of Joy Clark, our native speaking
>     technical editor.  In this category, we scored worst on
>     "Helpfulness" (3.5).  We interviewed the students to find out how
>     we could improve this (see below).
>   * Six users rated the tutorial, three the reference, and only one
>     the FAQ.  We were surprised how little the reference was used.
>   * The tutorial got the worst rating on completeness (3.3), which we
>     found surprising, as the tutorial wasn't meant to be complete
>     (that's what the reference section is for).  More pointers to the
>     reference section may be useful to remedy this (see WP4-3 below). 
>     Users found the chapter well-structured (4.2) and easy to find
>     information (4.0).  Once again, text style was leading with 4.7.
>   * The reference section was considered fairly complete (4.0) and
>     helpful (4.0), while structure (4.7) and completeness (4.7) got
>     even better grades.  The reference section got only 4 and 5 star
>     ratings in all categories!
>   * With only one response, we don't consider the feedback on the FAQ
>     representative.  Answers vary between completeness (2) and text
>     style (5), and all answers average to 3.5.
>   * The HTML-Version of the handbook got the best grade (4.2) and was
>     used by the most people (6).  Four users used the PDF version and
>     rated it at 3.5.  Only one person rated the Eclipse Help version
>     (3.0).
>
> Overall, we were content with the result, considering the resources
> that we had available.  From the survey we already had a few ideas on
> how to improve things.  We had additional discussions with the
> students to hear their thoughts, and to align them with our proposed
> improvements.  We got two main criticisms:
>
>   * The last two chapters of the tutorial came "out of the blue" and
>     didn't provide enough guidance.  This was understandable, as the
>     first chapters were written from scratch for the tutorial, while
>     the last two (celebrity and location access controller) were
>     ported from the Wiki.  We already started to build them up, and
>     will continue to do so in the forth iteration.
>   * As novices, the students spent most of their time with the
>     tutorial, while they used the reference relatively little or not
>     at all.  We will address this issue by providing more pointers
>     from the tutorial to the reference section.
>
>
>     Next Steps
>
> Based on this, and based on the tasks in our backlog, we propose the
> following tasks for the fourth and last iteration.  These are
> documented with additional detail
> <http://wiki.event-b.org/index.php/Documentation_Overhaul_DoW#Forth_Iteration>
> on the wiki:
>
>   * WP4-1: Improve Tutorial Chapters 2.9 and 2.10
>   * WP4-2: Completion of the Reference Section
>   * WP4-3: References and "Further Reading" Sections in Tutorial
>   * WP4-4: Coordination with Systerel to make the Rodin Handbook part
>     of the Distribution
>   * WP4-5: Polishing
>   * WP4-6: Final Review
>
> What you see here is the work of Lukas Ladenberger, Daniel Plagge and
> Joy Clark, who all did a terrific job, and myself.
>
> We encourage you once more to provide your feedback now, as we are
> about to start the final iteration on this project.
>
> Best,
>
> - Michael
>
> -- 
> Michael Jastram (http://www.jastram.de, +49 (162) 274 83 94)
> Geschäftsführer, Formal Mind GmbH (http://formalmind.com)
> Wissenschaftler, Heinrich Heine Universität Düsseldorf (http://www.stups.uni-duesseldorf.de)
> 1. Vorsitzender, rheinjug e.V. (http://www.rheinjug.de)
>

-- 
Michael Jastram (http://www.jastram.de, +49 (162) 274 83 94)
Geschäftsführer, Formal Mind GmbH (http://formalmind.com)
Wissenschaftler, Heinrich Heine Universität Düsseldorf (http://www.stups.uni-duesseldorf.de)
1. Vorsitzender, rheinjug e.V. (http://www.rheinjug.de)