Re: FW: ACTION-9: Propose a new structure for the Use Cases and Requirements document from Arnaud Le Hors on 2012-08-24 (public-ldp-wg@w3.org from August 2012)

From: Arnaud Le Hors <lehors@us.ibm.com>
Date: Fri, 24 Aug 2012 10:22:07 -0700
To: public-ldp-wg@w3.org
Message-ID: <OF00E97A1C.67942CAE-ON88257A64.005F1674-88257A64.005F697A@us.ibm.com>
I agree the proposed structure looks good.

I don't think we need to create another page. Let's just use the existing 
wiki page. We have access to the history anyway and we can simply mark the 
two sections with appropriate notes explaining what each part is about. 
Something like:

======== Below is an example of what the restructured document would look 
like ========
...

======== Below is the original content, before restructuring ==========
...
--
Arnaud  Le Hors - Software Standards Architect - IBM Software Group


Steve K Speicher/Raleigh/IBM@IBMUS wrote on 08/24/2012 09:41:48 AM:

> From: Steve K Speicher/Raleigh/IBM@IBMUS
> To: public-ldp-wg@w3.org, 
> Date: 08/24/2012 09:44 AM
> Subject: Re: FW: ACTION-9: Propose a new structure for the Use Cases
> and   Requirements document
> 
> I like the proposed approach quite well.  I think it would help me get a 

> better feel of how well it works if we have some real content to test 
> drive it with.  Perhaps we can create a "sandbox" page for now and leave 

> the current one as a "catalog" of items.  We can merge (eliminate the 
> sandbox) once we are happy with the layout.
> 
> Thanks,
> Steve Speicher
> IBM Rational Software
> OSLC - Lifecycle integration inspired by the web -> 
> http://open-services.net

> 
> > From: Arnaud Le Hors/Cupertino/IBM@IBMUS
> > To: public-ldp-wg@w3.org, 
> > Date: 08/24/2012 12:19 PM
> > Subject: Re: FW: ACTION-9: Propose a new structure for the Use Cases 
and 
> 
> > Requirements document
> > 
> > [resent to the proper list] 
> > See below.
> > --
> > Arnaud  Le Hors - Software Standards Architect - IBM Software Group
> > 
> > 
> > 
> > 
> > From:        "Steve Battle" <steve.battle@sysemia.co.uk> 
> > To:        Arnaud Le Hors/Cupertino/IBM@IBMUS, Steve K 
Speicher/Raleigh/
> > IBM@IBMUS, <michael.hausenblas@deri.org>, 
> > Date:        08/24/2012 08:45 AM 
> > Subject:        FW: ACTION-9: Propose a new structure for the Use 
Cases 
> and 
> > Requirements document 
> > 
> > 
> > 
> > Arnaud, Steven, Michael, 
> > 
> > I sent the following email to the mailing list yesterday, but as this 
> was 
> > the first message I’d sent to the list, it appears to have been 
delayed 
> (I 
> > have given archival approval ) . 
> > Anyway, the content is reproduced below, for yourself and the use case 

> co-
> > editors to review. 
> > I’m happy to discuss this Monday. 
> > 
> > Steve Battle 
> > 
> > 
> > From: Steve Battle [mailto:steve.battle@sysemia.co.uk] 
> > Sent: 23 August 2012 18:05
> > To: public-ldp-wg@w3.org
> > Subject: ACTION-9: Propose a new structure for the Use Cases and 
> Requirements document
> > 
> > The following is the proposed structure of the LDP 'Use Cases and 
> > Requirements' Document. Rather than basing this template on any one 
> prior 
> > example, I've chosen to look to these as exemplars of a particular 
> feature, 
> > with the aim that this document will combine the best of the best. The 

> main
> > change is the relabeling of the existing use-cases as 'User Stories', 
> and 
> > the introduction of a new 'Use Cases' section that will catalogue the 
> > complete set of behaviours of LDP compliant systems. The text below is 

> > representative of the document outline, using wikitext to indicate 
> section 
> > levels. I hope not to ignite any wars over the terms 'user story', 
'use 
> > case', and 'scenario' as used in different communities; aiming to be 
> > compatible with as many different approaches as possible, from 
> lightweight 
> > to formal. The most contentious point may be the distinction between 
> user 
> > stories and use cases, to allow the relationship between them to be 
> > something other than 1 to 1, as is often the case with larger 
multi-line 
> user stories.
> > 
> > I invite comment on the layout (particularly from my co-editors), and 
if 
> the
> > response is favourable, I'll edit the wiki accordingly. The actual 
work 
> on 
> > isolating, identifying, and documenting the use-cases will remain work 

> to-be-done. 
> > 
> > Steve. 
> > 
> > 
> > =Linked Data Platform Use Cases And Requirements= 
> > 
> > ==Scope and Motivation== 
> > 
> > ==User Stories== 
> > ===<USER STORY>=== 
> > A statement about system requirements written from a user or 
application 
> 
> > perspective. They can be obtained during informal discussion with 
users, 
> 
> > often as a prelude to a more formal requirements gathering process 
[1]. 
> They
> > are lightweight and informal and can run from one line to a paragraph 
or 
> two. 
> > (e.g. <
> http://www.w3.org/2005/Incubator/webid/wiki/User_Stories_and_Use_Cases

>). 
> > ====Analysis==== 
> > Analysis of the user story can reveal specific use-cases and 
> non-functional 
> > requirements (e.g. <http://www.w3.org/TR/dap-policy-reqs/>). We don't 
> > presume that each user story corresponds to a single use case. 
> > 
> > ==Use Cases== 
> > Functional requirements modeled as use cases. This section provides a 
> > catalogue of use cases, each of which may be derived from one or more 
> user stories. 
> > ===<USE CASE>=== 
> > Use cases, while still telling a story, are more structured [2], 
> cataloguing
> > who does what with the system, for what purpose, but without dealing 
> with 
> > system internals [3]. We would typically identify the use case with a 
> > reference number (see e.g. <http://www.w3.org/TR/rdb2rdf-ucr/>), along 

> with 
> > a description, actors, pre/post conditions, and behaviours. UML use 
case 
> 
> > diagrams (a form of behaviour diagram) may be used, but aren't 
> necessary. 
> > Use cases act like the hub of a wheel; with spokes supporting 
> requirements 
> > review and traceability, scenario-based analysis, end-to-end testing, 
> and 
> > integration with non-functional, or quality requirements. 
> > ====<SCENARIO>==== 
> > Scenarios are more focused still, representing a single instance of a 
> use 
> > case. Scenarios may be lightweight narratives (e.g. <
> http://www.w3.org/TR/

> > media-frags-reqs/>), or modeled as interaction diagrams. Each scenario 

> may 
> > lead to the development of one or more test cases (e.g. 
> http://www.w3.org/

> > TR/xquery-use-cases/) 
> > 
> > ==Requirements== 
> > ===Accepted Requirements=== 
> > Use-Cases may document behaviours that are ultimately deemed out of 
> scope. 
> > This section may identify use cases that are accepted (e.g. http://
> > www.w3.org/TR/skos-ucr/) 
> > ===Additional Functional Requirements=== 
> > This section lists supplementary functional requirements that are not 
be 
> 
> > captured as use-cases. These may be specific algorithms, 
state-machines, 
> 
> > business processes, or other behavioural models that define what a 
> system is
> > supposed to accomplish. 
> > ===Non-Functional Requirements=== 
> > This section lists non-functional or quality requirements, and the use 

> cases
> > they are derived from (if any) (e.g. <
> http://dvcs.w3.org/hg/gld/raw-file/

> > default/dcat-ucr/index.html>). These may be derived from and organized 

> by 
> > quality attributes. 
> > 
> > ==Acknowledgements== 
> > Including acknowledgement of input from other working groups (e.g. 
> <http://
> > www.w3.org/TR/powder-use-cases/>). 
> > 
> > ==References== 
> > [1] Alistair Cockburn, Writing Effective Use Cases, ISBN: 0201702258. 
> > [2] Derek Coleman, A Use Case Template: draft for discussion, <http://
> > www.bredemeyer.com/pdf_files/use_case.pdf>. 
> > [3] Ruth Malan, Dana Bredemeyer, Functional Requirements and Use 
Cases, 
> <
> > http://www.bredemeyer.com/pdf_files/functreq.pdf> 
> > 
> > -- 
> > Steve Battle
> > Semantic Engineer
> > 
> > Mobile: +44 (0)7503 624 613 
> > E-mail: steve.battle@sysemia.co.uk
> > Web: www.sysemia.com 
> > 
> > Sysemia Limited
> > The Innovation Centre, Bristol &  Bath Science Park, Dirac Crescent, 
> > Emerson's Green, Bristol BS16 7FR
> > Registered in England and Wales. Company Number: 7555456
> > 
> > DISCLAIMER 
> > Information contained in this e-mail is intended for the use of the 
> > addressee only, and is confidential and may also be privileged. If you 

> > receive this message in error, please advise us immediately. If you 
are 
> not 
> > the intended recipient(s), please note that any form of distribution, 
> > copying or use of this communication or the information in it is 
> strictly 
> > prohibited and may be unlawful. Attachments to this e-mail may contain 

> > software viruses which may damage your systems. Sysemia Ltd have taken 

> > reasonable steps to minimise this risk, but we advise that any 
> attachments 
> > are virus checked before they are opened. 
> >
Received on Friday, 24 August 2012 17:23:14 UTC