[sword-devel] OSIS Call For Use Cases

[sword-devel@crosswire.org]

As most of you know, we've been working closely with ABS, SBL, SIL, and
others to develop a new Biblical text markup language.  The initiative
is called OSIS and you can read about it at:
http://www.bibletechnologies.org

Well, the time has come for us to discover all of the needs that this
new markup language will meet.  We would love to have each of you
participate in this effort.  We've divided up domains into 8 categories
and created working groups for each.  There may be more in the future,
but please, first attempt to categorize your use case into one of these
groups.

Patrick Durusau from SBL has written a draft of a use case tutor and
template that I've attached to the end of this message.

Please browse the information at: http://www.bibletechnologies.org
Review the (moderately light, thus far) traffic on the working groups'
newsgroups by following directions at:
http://www.bibletechnologieswg.org (note slightly different link).
Read through the tutor below.

And if you've gotten this far :) we'd love to hear your wish-lists!

We're meeting in 2 weeks to review all of the submissions, so please get
yours in before then.  Please post them to the public newsgroup to which
they relate, or to this list and I will be sure they are included in the
review stack.

THANK YOU for your participation, in advance!  Let's show our support
for the effort.  It is great for these organizations, and others, to
work toward a common markup shared for all of their texts!

	Christ Rules!,
		-Troy.

____________________________________

Use Case Tutor and Template:
___________

Note that I start with an example template with instructions, then the 
bare template and then use that template to cover what may seem like the 
same use case, twice. It is not since I use two different primary 
actors, who have different goals and requirements (particularly once you 
get to more details in the use cases). 


*****OSIS Use Case Template***** 

Primary reference for all the following reflections is Alaisdair 
Cockburn, Writing Effective Use Cases, Addison-Wesley, ISBN: 
0-201-70225-8. This is not an endorsement of Cockburn's book over 
another than may be your favorite. I have found it useful and have not 
attempted a comparison with other works on this topic. Needless to say, 
Cockburn is not responsible for any mistakes, mis-interpretations or 
other poor use of his materials in these postings. 
I suggest the following form (it will get more detailed later this month 
(August, 2001) for preliminary use cases: 

Primary Actor: Student writing a research paper. 
The who question. All use cases must start with a particular actor in 
mind. This helps focus the use case into something manageable. 
In my example: Student writing a research paper. (Has different goals 
and requirements from bible society, publisher, software vendor, 
scholar.) 

Scope: Scriptural references in a student research paper by verse to the 
KJV of the NT text. 

How I got there: 
The use case under consideration. Needs to be fairly narrow. Later 
analysis can combine use cases but too broad a use cases at the 
beginning means we will (not if, will) miss use cases that will be 
important later on. 
Example 1: If my use case were "all references that may occur in any 
type of literature, to be automatically available", it would be very 
difficult to know where to start in terms of describing a set of 
requirements, much less undertaking the research on such a question. 
Example 1a: My use case is: "all biblical references that may occur in 
any type of literature." (Not picking on the scriptural reference folks, 
it happens to be of personal interest and something I know a little 
about.) Still too broad to be useful. 
Example 1b: My use case is: "all scritural references by verse to any 
scriptural text." Better, note that we are now talking about scriptural 
references (it assumes we know what it meant by that) to a scriptural 
text (similar assumption here). 
Example 1c: My use case is: "all scriptural references by verse to the 
NT text." Better because we are getting closer to a manageable use case, 
still way too broad. 
Example 1d: My use case is: "all scriptural references by verse to the 
KJV of the NT text." Only looks specific enough. Note that we don't yet 
know where the references are being made. Too open ended. 
Example 1e: My use case is: "Scriptural references in a student research 
paper by verse to the KJV of the NT text." This is as far as I want to 
take this example, but it could be better worded in several places. Note 
that even at this stage I am still assuming we know what is meant by a 
"student research paper." 
It should also be noted that I did not try to say how anything would be 
done. After years of working in markup that is not easy! Please, ignore 
what you know or think you know about SGML/XML or other mechanisms for 
the use cases. Plenty of time for solutions once we understand the 
problems. 

Level: Summary (default at this level of analysis, will change later) 
Stakeholders and Interests: 
Who is affected? Who has an interest? 
Student: Wants to cite biblical text. Just that or should it draw the 
text into the paper? (probably a separate use case) 
Professor: Wants to check citations? (a separate use case) 
Note that I am (artificially) assuming only two parties to this 
transaction. Wholly artificial. 

Main Success Senario: 
For our purposes I would suggest that this be simple prose about what 
happens when it goes right. DO NOT attempt to break it down into steps 
for encoding/processing, etc. That will simply cover up some of the 
information we want to gain from the use cases. 
Continuing with my example: 
Student wants to cite Matthew 8:8 from the KJV in his paper and simply 
have the citation present or have the text automatically inserted or 
follow his professor's stylesheet or make it available on the web. 
Success from his standpoint is insertion of the proper reference, all 
the other is processing beyond his immediate concern (although of 
concern to others). 


****************** 

Use Case Template: Your Use Cases should have the following headings 
(simply prose following each one) 
Date: 
Working Group Name: 
Use Case Number: (leave blank, assigned by OSIS editors for tracking) 
Name: 
Email: 
**********Use Case 
Primary Actor: who? 
Scope: remember to narrow, write multiple little use cases! 
Level: Summary 
Stakeholders and Interests: who is affected? 
Main Success Senario: describe what the principal actor does, what is 
success to them? (the more prose the better) 
**********************End Template 

Example of dividing use cases: 

****PLD Use case #1***** 

Date: August 5, 2001 
Working Group Name: Periodical Citations Group 
Use Case Number: 
Name: Patrick Durusau 
Email: pdurusau@emory.edu 
Use Case 
Primary Actor: Academic/scholar 
Scope: Citation of journals or monographs in articles 
Stakeholders and Interests: scholars (does the citation make sense, can 
others find it) , publishers (how is it treated in publishing, can it be 
resolved to electronic versions) 
Main Success Scenario: 
Entry of journal or monograph citation while authoring article. Other 
usages and processing beyond their interest at that point. 


Versus: 

****PLD Use case #1***** 

Date: August 5, 2001 
Working Group Name: Periodical Citations Group 
Use Case Number: 
Name: Patrick Durusau 
Email: pdurusau@emory.edu 
Use Case 
Primary Actor: Publishers 
Scope: Submission of articles or monographs with citations of journals 
or monographs 
Stakeholders and Interests: Editorial staff (proofing and correction), 
typesetters (style for presentation), incorporation into printed or 
electronic collections, cross-linking to online resources. 
Main Success Scenario: 
No or little manual intervention in the processing of articles or 
monographs for publication. Editing, proofing, styles, and publishing as 
either print or electronic versions. 


*************** 

Note that while both are concerned with citations, i.e., 116 JBL 
401-410, they have radically different views (upon examination of the 
use cases) for success. The scholar wants to be understood while the 
publisher has a more process driven view of the process. For reference 
purposes the citation could be some unique number assigned to every 
article but that would probably not meet the scholars need for people to 
recognize the reference. ;-) 
Note that I have attempted to avoid saying how any of this would happen. 
That is crucial if we are going to arrive at use cases that will keep us 
from creating a standard that has serious holes in it. Good use cases 
will not necessarily prevent such mistakes but they can give us a 
fighting chance at a useable standard. (Note I did not say perfect, just 
useable is a big enough step for the moment.) 


Use Case Template: Your Use Cases should have the following headings 
(simply prose following each one) 
Date: August 6, 2001
Working Group Name: 
Use Case Number: (leave blank, assigned by OSIS editors for tracking) 
Name: 
Email: 
**********Use Case 
Primary Actor: who? 
Scope: remember to narrow, write multiple little use cases! 
Level: Summary 
Stakeholders and Interests: who is affected? 
Main Success Senario: describe what the principal actor does, what is 
success to them? (the more prose the better) 
**********************End Template