Review of the structure of the requirements document - take 2

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

Received on Saturday, 11 October 2008 19:42:30 UTC