Re: Review of the structure of the requirements document - take 2

Hi Elisa

Thank you very much for this helpful review.

I have made a new update of the Req  [1].Hope it will address your concerns.

As you said, all content and connections between UC-Req-Feature were
already  there (sometimes implicitely), in fact mainly in the Feature
and Table sections. But indeed some links between the 3 sections
needed to be made more explicit.

1. To that end, as explained at the top of the UC section,
-  I introduced a 'pattern' in the UC section: Overview/ Requirements/
Example :
thus each UC now *explicitely* refers to a specific req with a
corresponding example, which is further used in section 5 and 6 (Table
6.2)
- I also added an hyperlink from each UC to this specific requirement,
which in turn points to the feature via another hyperlink

This provides the required glue needed to link UC-Req-Feature. It also
allows to navigate from a UC with a short
informal example -to-> a specific requirement -to-> a specific
feature, with the same example represented in OWL 2.

It was faster for me to do so and to elicit the connections between
UCs-Examples /Requirements/ Features as I did.
Indeed, 1) each UC points to *several* requirements, 2) there is
already a short example (even several) for each feature/requirement
both informal and  in OWL 2 syntax in the Feature section 3) Moreover,
restructuring all and moving the content from one section to another
would imply much work. We should also be carefull not to introduce
redundancies and to repeat nearly the same in the different sections.

2. The Requirements section is  voluntarly quite brief. Its main role
is to bridge between UCs and Features. However we might perhaps
improve it to better stress the "why do I care"/"what do we need that
isn't there in OWL 1" if it's not clear enough.

I hope this is acceptable and will meet your main concern regarding
the sections UCs and Requirements.

3. The TBDs (Implementation and Theory) have still to be filled

I am aware of other details wich have still to be fixed. All links
have to be checked, the  narrative may also be improved in different
places, etc

BTW I wonder whether it's useful to spend much more time on the
Requirements now or whether we might have perhaps a non perfect but
acceptable version as fastly as possible, and move our energy on the
QRG (for which we may take benefits of this experience).

Regards

Christine

[1] http://www.w3.org/2007/OWL/wiki/RequirementsDraft

2008/10/11 Elisa F. Kendall <ekendall@sandsoft.com>:
>
> Hi all,
>
> This revision of the document is clearly a significant improvement over the
> prior version. The user role section (section 2) is much better, the use
> cases are summarized better, there are more examples and better descriptions
> in the features section, etc.
>
> I'm still left feeling that it doesn't really answer the "what can't we do
> in OWL 1 that OWL 2 addresses and why do I care" question as well as I would
> like.  I say this from the perspective of working with a number of our
> customers who include existing users of OWL, who have to explain to their
> bosses why they should be spending time following what the working group is
> doing, or upgrading to newer versions of tools, or revising their ontologies
> to take advantage of the new features, all of which requires budget
> justification.  Some of this is implicitly there, but could be made more
> explicit.  The use case descriptions are often too general, or at least
> there seems to be a big mental leap that one has to take to go from the use
> case description to the requirement, and from the requirement to the feature
> description.
> Some specifics on what could be done to address this from an organizational
> issue:
>
> 1. Section 2 is an order or two of magnitude better than the prior version.
>  2.6 and 2.7 still need a bit of "normalization", including the heading for
> 2.7, and the addition of use case references for both user role
> descriptions.  2.6 could be combined with 2.4, if the discussion in 2.4 is
> augmented to include numerical information, representing scientific units,
> etc., which is relevant to a number of research communities.  With regard to
> 2.7, if you change the title to something like "Existing OWL 1 Application
> Developer", that might be enough.
>
> 2. None of the user role descriptions track back to use case 13, and one
> refers to use case 21, but there are only 20.
>
> 3.  I stand by my previous comments on the use cases (section 3), regarding
> how to better organize them.  The use case descriptions tend to be overly
> general, and the leap to the new features they motivate is too great.  The
> specific use case summaries could be tightened up a bit more, focusing on
> the "what we can't do" today, and linking to the original use cases as part
> of the published document, perhaps as a separate appendix.
>
> For each use case in this document, I'd like to see three headings, (1)
> "Problem Description", (2) "Issue" or "Feature Gap" or "Requirement" (which
> in some cases is represented, at least very generally, in the last couple of
> sentences of the use case summary, e.g. in #2, , but in many cases is really
> missing altogether)-- this is the piece that should narrow the gap I'm
> currently sensing; and (3) change "Requires" to "Motivates".  Presumably you
> are planning to link the keywords that identify the features to the
> paragraphs in section 4 that describe the requirements, if not, this would
> also help, in addition to linking to the features themselves.  Good
> descriptions of the "feature gap" would improve readability and the value of
> this document considerably.
>
> 4.  The requirements section remains way too terse in places - sometimes
> jumping to a technical feature description rather than summarizing what the
> user wants/needs to do.  This should be more educational from a "why do I
> care"/"what do we need in OWL that isn't there now" perspective.
>  Reorganization of the use cases will help, but in this section I would like
> to see real examples from one of the relevant use cases for each
> requirement, highlighting what you can't do in OWL 1/what's missing,
> followed in the features and rationale section with the solution using OWL
> 2.
> What I think would also be helpful is uniform treatment and a repeated
> pattern between sections 4 and 5 -- requirement / example in section 4,
> feature / solution in section 5, with consistent headings to assist the
> reader in working through it.  Having the "after" part in section 5 is good,
> and explanations there are useful - I'm looking for the "before" part of the
> example in section 4.  An alternate approach would be to combine sections 4
> and 5, with subheadings for each feature that would include: Requirement,
> Example, Feature, Solution, Theoretical and Implementation perspectives, if
> we need the last two (which I'm still not sure about, but perhaps for a very
> broad readership it's useful, and one can hide it), highlighting the gap in
> the example part.  Whether or not the two chapters are combined, the end
> result should really describe the gap more specifically and show how the new
> feature addresses it, which should greatly improve the flow.
>
> 5. This is a fairly long document - I could see both cleaning up and
> including the original use cases, as an appendix, and splitting this into
> several linked documents, especially if sections 4 and 5 remain separate but
> are augmented substantially to address the "why do I care" question.  The
> whole document should be spell checked, though it's better than previously,
> and section 5 in particular needs a review for copy/paste errors.  Several
> examples say things about taking OWL 1 ontologies and pre-processing them
> into OWL 1 ontologies (the former should be OWL 2?).  Also, several of the
> examples have double headings "Example:" and "Examples".  A number of the
> theoretical and implementation sections need work, similarly for the
> profiles discussion, etc. but I'm assuming you haven't gotten to it yet.
>
> The tables are helpful, but should have live links to the use cases,
> requirements, and features for ease of use.
>
> Best regards,
>
> Elisa
>
> [1] http://www.w3.org/2007/OWL/wiki/RequirementsDraft
http://www.w3.org/2007/OWL/wiki/RequirementsDraft
>
>



-- 
Christine

Received on Sunday, 12 October 2008 19:49:45 UTC