Forum: RSpec Cucumber Feature Scenario critique

Announcement (2017-05-07): www.ruby-forum.com is now read-only since I unfortunately do not have the time to support and maintain the forum any more. Please see rubyonrails.org/community and ruby-lang.org/en/community for other Rails- und Ruby-related community platforms.
James B. (Guest)
on 2009-02-20 19:09
When I initially began working with cucumber and developing features and
steps from existing code I went through a process (prompted by the
members of this group) of developing increasingly abstract
(declarative?) wording for the feature scenario steps.  Now, I am
finally at the stage where I am using features to drive new code.  I
would appreciate very much some advice on how to word a design desire
into a feature scenario.

The example I have chosen is that of a client.  In our design and
requirements discussions we have arrived at the idea of "client" being
that of an ephemeral "role" assigned to a durable "entity".  A client
role is thus conceived as episodic in nature. An entity can be a client
for a period of years, then dormant for a period (whether due to change
in their business patterns or a departure to a competitive service) and
then active again.

For tax reasons it is important to know precisely when a client was
active and when they were not.  For business reasons it is important
that dormant accounts be deactivated as soon as this state is detected
and confirmed.  It is however, vital that all previous history of
activity not be disturbed by any changes in status and that all the
cumulative history of a single legal entity be kept together.

The questions I have relate to how best put this down as a set of
features or scenarios within a feature or features. I am toying with the
idea of a general, application wide, feature file (app.feature) that
contains the barest statement of what each major component or element of
the evolving application requires.  Then, as the step definitions are
expressed, the detailed features are arranged in hierarchy of files
according to their anticipated nature (external component, model,
controller, view, service or library so far).

So to begin with, at the highest level I think something like this might
serve:

app.feature
Feature: A Web Based Business Application for Transportation and Customs
  In Order To: Conduct Routine Business
  An: Authorized User
  Should: Securely Access the Web Application
  To: Reduce Costs  #The work will be done anyway and the price won't
change

  Scenario: The Application Has Authorized Users
...

  Scenario: The Application Has Entities
...

  Scenario: The Application Has Clients
    Given I have a user named "admin"
      And the user named "admin" authenticates
      And the user named "admin" is authorized to "add" "clients"
    When they visit the add new client page
      And they provide valid client data
      And they submit the new client
    Then they should see a new client added message

The app.feature file will contain no further specifics respecting
clients.  To deal with these specifics I will later create a
model/clients/client.feature file (or files) that will detail the
implementation of that model.  The step definitions given above will go
into model/clients/step_definitions/client_steps.rb

I think this approach will work but I really have no experience with
organizing a large scale project around BDD.  Any insight and experience
that anyone can provide is greatly appreciated.

As a supplemental issue: We use a project administration system
(Redmine).  Have any of you adopted practices with respect to the
relationships between issue tickets and feature scenarios that you found
useful?
Michael L. (Guest)
on 2009-02-20 22:18
(Received via mailing list)
I would suggest a different approach to organizing the features.  In
particular I would recommend the features be used to test
implementation invariant aspects of the system.  Our features are
whole stack sequences that involve views, controllers, and models in
almost every case.  We test the "system" not the parts.  In the ideal
case you will specify the system up front so little should change from
bug reports unless they are really a change in requirements.
Requirements changes have a different workflow than implementation
bugs.  I would recommend you track that difference in your project
management system.  Keep an eye on how much changes after
implementation to measure how good your requirements capture has been.

Michael
James B. (Guest)
on 2009-02-20 22:46
Michael L. wrote:
> I would suggest a different approach to organizing the features.
...
> Requirements changes have a different workflow than implementation
> bugs.  I would recommend you track that difference in your project
> management system.  Keep an eye on how much changes after
> implementation to measure how good your requirements capture has been.
>
> Michael

This is probably another case where I simply have not yet established in
myself a sensible mental framework for working with BDD.  Bear with me
as I struggle through this adjustment.

My apprehension so far is that features are intended to drive out the
design requirements by explicitly stating concrete examples of what the
client considers desirable.  The idea of a contract between developer
and client arises from the mutual agreement on functional expression as
given in the feature scenarios.

Definition steps, on the other hand, are the purview of the
design/development team.  They can take any reasonable form so long as
they:

1. test the functionality of the implementation in a meaningful way
2. meet the requirements of the scenario

Unit tests are the purview of the implementers and are tied to their
respective code modules.

My concern arises from a desire to establish how I should organize the
features in relation to one another.  Given my understanding respecting
features I proceeded from the belief that one could arbitrarily start
anywhere in the system design. Features would allow one to elaborate
both up and down in detail as appropriate for the stage of the project
and the area of immediate concern.

As a practical matter it appears to me that the logical flow is
Authentication/Authorization, administrative functions relating to
record maintenance, algorithmic user applications, report generation,
utilities, and finally loose ends.  The application can be sliced so
that all or most of these issues are dealt with within one specific
aspect before tackling another.

We are using Redmine to administer the project so milestones, issue
tracking  and such are kept in there.  However, I have acquired this
notion of functional decomposition relating to features.  As i see it
the basic gross requirements of the system (there will be clients, there
will be invoices, etc.) are expressed as scenarios in a feature file
somewhere.  Then as more detail is driven out more features are inserted
into the composition tree as appropriate.

Is this completely at odds with what I should be doing?
Stephen E. (Guest)
on 2009-02-21 06:04
(Received via mailing list)
On Fri, Feb 20, 2009 at 3:46 PM, James B. <removed_email_address@domain.invalid>
wrote:
>
> As a practical matter it appears to me that the logical flow is
> Authentication/Authorization, administrative functions relating to
> record maintenance, algorithmic user applications, report generation,
> utilities, and finally loose ends.  The application can be sliced so
> that all or most of these issues are dealt with within one specific
> aspect before tackling another.
> [ . . . ]
>
> Is this completely at odds with what I should be doing?

Well...  In my opinion, yes and no.  I personally have my doubts about
the 'waterfall' chain of serial projects you're talking about here.
"We will do authorization.  Then we will do admin screens.  Then we
will..."  For one thing it's not very agile; what you learn when you
start getting requirements for reporting will surely change what you
thought was 'complete' earlier.  And it seems harder to sell and keep
the client engaged because the sexy stuff, the business value the
client *cares* about, doesn't happen until somewhere in the middle.
It's my experience that the most effective projects begin early with
things you can *show.*

You can't really show off authorization.  It's visible, but it doesn't
excite people. You need to have some basic stuff in for it before you
can open it up to the public, but it's not necessarily Square One, and
treating it like it is might overemphasize its importance.  (And I say
this as someone who recently spent a couple of days designing a
hierarchical polymorphic authorization framework from hell
[http://tinyurl.com/d6w4t8] so don't think I'm discounting it
completely.)

So I'd personally worry less about getting all your administrative
ducks in a row before you start to do anything interesting, and
instead _start_ with whatever drives the most value to your company
and then build the support framework around it only when it's needed.
You might find when you do that that you need fewer struts and pins
and guywires than you thought you did.

...But that has nothing to do with RSpec and very little to do with
BDD, except in a very general 'start with the behavior you *care*
about the most' sense.  Odds aren't high that the thing you care about
the most in the application is logging in.  So spec that out later and
start with something more interesting.  You'll hit the ground running.

Otherwise, it all looks fine.  >8->


--
Have Fun,
   Steve E. (removed_email_address@domain.invalid)
   ESCAPE POD - The Science Fiction Podcast Magazine
   http://www.escapepod.org
James B. (Guest)
on 2009-02-21 06:33
Stephen E. wrote:

>
> Well...  In my opinion, yes and no.  I personally have my doubts about
> the 'waterfall' chain of serial projects you're talking about here.
> "We will do authorization.  Then we will do admin screens.  Then we
> will..."

Perhaps I expressed myself poorly, or perhaps I am missing something
fundamental in your commentary.  I did not mean to imply that an
authorization system had to be "finished", and then record maintenance
system "done", before getting into the interesting bits.  I only meant
that having tried to start in the middle, with the interesting bits
insofar as the client is concerned, I quickly discovered that some
minimal provision for authentication and record maintenance seemed a
prerequisite to support work on the middle.

For some reason I seem to have an aversion to using fixtures for this
purpose and prefer some sort of interactive UI, however primitive.  For
instance this is my authorization implementation:

  def authorized?(auth_request={})
    #myrole = auth_request[:role]
    #myctlr = auth_request[:controller]
    #myactn = auth_request[:action]
    return true if self.administrator
    return false
  end

I did not spend very much time or effort on this but it seemed best to
provide the authorization interface when working on user facing
components.  The future elaboration of the authorization system will
nonetheless still present the same interface to the rest of the system,
or so I intend.

What I am grasping at understanding is how elaborate the feature files
should be and how the interrelationship between features are best
managed or expressed.
Mark W. (Guest)
on 2009-02-21 06:40
(Received via mailing list)
On Fri, Feb 20, 2009 at 8:02 PM, Stephen E. 
<removed_email_address@domain.invalid> wrote:
>
> You can't really show off authorization.  It's visible, but it doesn't
> excite people. You need to have some basic stuff in for it before you
> can open it up to the public, but it's not necessarily Square One, and
> treating it like it is might overemphasize its importance.

Agreed. I've seen projects that weren't public yet, didn't do anything
useful, yet had a full authorization model - which did nothing but
annoy new developers.

///ark
Andrew P. (Guest)
on 2009-02-23 19:01
(Received via mailing list)
James,

Personally I think your missing the point entirely about BDD. The
fundamental idea of BDD is to drive/guide the relationship between the
customer and developer. So you shouldn't be having meetings with
customers
that arrive with

" the idea of "client" being that of an ephemeral "role" assigned to a
durable "entity"

Instead you should have meetings with customers that end up with written
features!

There is no way I would expect any customer I've ever worked with to
comprehend

" the idea of "client" being that of an ephemeral "role" assigned to a
durable "entity"

nor would I expect any developer I've ever worked with to turn this into
meaningful code. And if that process was completed I'm quite sure the
chances of the code meeting the customer expectation would be zero.

Having up front requirements meetings that produce that sort of
language,
and then having you work afterwards work on top of that to produce
features
is just silly. Agile tools don't work with this approach.


I'm speculating wildly here, but it seems to me in your organisation you
are
trying really hard to get your development side into cucumber features
and
automated testing which is admirable, but the focus is completely in the
wrong place. The focus has to first be about getting your customer
really
into producing features with you. If you achieve that then what should
happen is

1. You and your custoimer meet often and work (rather than just talk)
together and produce features
2. Your customer prioritizes the features
3. You give your developers the features and say implement this
4. When the features pass the customer reviews things

Iterate that a few thousand times and you might end up with a pretty
good
system

If your present your developers with well written features and the
cukes.info link and the mailing list link, and a bit of your time to get
them up to speed, then they really should have no problem embracing
cucumber. I mean how many developers have ever been given clear
instructions
(that can easily be executed as acceptance test) about what to do, from
anyone never mind directly from the customer!

Finally as far as feature organisation is concerned it really does not
matter at the moment. The important thing is to write and then implement
good features and do it now, because your first ones won't be very good,
and
you won't learn to write better ones until you've iterated and produced
something. The features will find a place as you write them and you will
probably have to change the structure and organisation of them many
times in
the project if you wish them to tell a clear story with that structure,
but
don't worry about that now - you've got enough to worry about.

Dan N.'s original BDD pages address much of the stuff involved in
actually writing features, and there was an IRC log with Aslak on here
which
I thought was very insightful about the dialogue involved in producing a
feature.

All best

Andrew

n.b. I'm expressing my opinions forcefully without much regard to tact
or
diplomacy. No offense in any way is intended :)

2009/2/20 James B. <removed_email_address@domain.invalid>
Stephen E. (Guest)
on 2009-02-23 20:05
(Received via mailing list)
On Mon, Feb 23, 2009 at 10:57 AM, Andrew P. 
<removed_email_address@domain.invalid>
wrote:
>
> The focus has to first be about getting your customer really
> into producing features with you. If you achieve that then what should
> happen is
>
> 1. You and your custoimer meet often and work (rather than just talk)
> together and produce features
> 2. Your customer prioritizes the features
> 3. You give your developers the features and say implement this
> 4. When the features pass the customer reviews things

To be fair, sometimes it isn't all that cut-and-dry.  This is
especially true for smaller projects or smaller organizations.  What
follows isn't a hypothetical example, it's my truth:

I'm the technology director for a non-profit academic society.  My
organization has 15 employees.  I'm the one who knows anything at all
about computers.  When I came on, I delegated *to myself* the
responsibility of getting rid of our current excremental Web site,
which is built on a lot of bad Microsoft ASP code and over 20 Access
databases (I kid you not), and replacing it with something I could
tolerate.  To me that means Rails or Merb.  I also decided that the
features we offer should be totally reexamined, and we should make a
site useful enough that our members come back frequently to support
their academic work.  And I decided that if we're going to do this, we
should do it *right.*  We should release it as open source and make it
good enough that other societies can use it.

My evangelism has spurred others in the organization into getting
excited too, and building up a proposal that they're now pitching to
raise some grant money for this.  (BTW, if anyone here knows of
organizations that support non-profit software projects, I'd love to
hear about it.)  With that grant money I'm hoping to get some interns
or co-ops or contractors to help me build this, because it's an
economic reality that they won't hire another programmer.  In the
meantime, it's just me.

What this means is that for all current software projects in my
organization, I am:

1.) The customer.
2.) The project manager.
3.) The developer.

Oh, and that's on top of all my other responsibilities, like keeping
the office network running, maintaining the current horrible Web site,
writing quick-and-dirty Access queries, or deciding how we're going to
handle videoconferencing between widely separated non-technical
committee members.  I put up with all that crap in order to make time
for the stuff that excites me.

There's nobody else.  My boss cares about what I'm building, but not
at a feature level appropriate for Cucumber.  He wants to know "Yes,
we're going to let people post their papers online."  "Yes, we're
going to have discussion forums."  "No, we're not going to use SQL
Server and I don't care if somebody before me already paid to license
it.  No.  Really, no."  And most of all: "Yes, I believe what we're
doing will enhance our value to our members, and increase enrollment
and improve our revenue, therefore justifying the budget increase I
just asked for."

I need to document that and help establish my business case, but not
with Cucumber.  Cucumber features could be supporting documentation,
but nobody wants to help me develop them.  I came up with this project
and I am driving the features.  There's no way I'm going to get
anybody else "really into producing the features with me," as you put
it, because as they see it that's my job.

I still use Cucumber, however.  Not to help me communicate with my
boss, but to keep things straight in my own head.  And later, if I get
the money I need and this *does* become a team project, having the
head start on good structured development will make it easier.

...So that's my reality.  Cucumber for collaboration isn't the value
for me.  I suspect that there are a *lot* of companies out there with
one-person IT departments that may fit into my situation, and
certainly a whole ton of personal projects where there was never any
money or 'business case' in the first place.  In those cases,
communicating features to "the customer" is just talking to oneself.
It may still have value, but it isn't about teamwork.

Anybody else in a situation like this?



--
Have Fun,
   Steve E. (removed_email_address@domain.invalid)
   ESCAPE POD - The Science Fiction Podcast Magazine
   http://www.escapepod.org
James B. (Guest)
on 2009-02-23 20:10
Andrew P. wrote:

>
> n.b. I'm expressing my opinions forcefully without much regard to tact
> or diplomacy. No offense in any way is intended :)
>
None taken.  I am trying, desperately, to move from one way of thinking
to another.  I expect it to be a painful process.

I am afraid the way that I express myself when reflecting on problems of
interpretation and understanding is somewhat different than what I do
with the client.  Of course, sometimes I just have to fill in for the
client. That is just one of the facts of life I need deal with.

You can interchange "ephemeral" (my word) for "transient", episodic",
"recurring" or "intermittent" according to taste but the idea is the
same.  The legal "person" endures, and their history is maintained, even
though periodically we do not legally represent them.  If and when an
entity restores the client relationship then the entity nonetheless
remains the same and their prior history is continued into the new
period of service.


The ticket for this item reads:

Description

Provide an interactive UI to add a client role to an entity and to
terminate an existing client role. Roles are conceived as "episodic" in
nature so that it should be possible to view the "history" of entity's
periods as a client.

The feature set for this (so far) is limited to the following:

# An Entity is a model of anything that has
# separate legal existance and standing for
# the purposes of contract law

Feature: Identify those entities that are clients
  In order to identify our clients
  An accounting user
  Should be able to assign an active client role to an existing entity
  To Increase Revenue


  Scenario: client role link is available from entities page
    Given I have a user named "auth_user"
      And the user named "auth_user" authenticates
      And the user named "auth_user" is authorized to "list" "entities"
      And I have an entity named "A Future Client"
      And the entity named "A Future Client" is not a client
    When they visit the entities page
    Then they should see an entity named "A Future Client"
      And the entity named "A Future Client" should have an add client
option

Hardly controversial stuff so far, I should think.  Of course, I have
been wrong before...
James B. (Guest)
on 2009-02-23 20:41
Stephen E. wrote:

>
> ...So that's my reality.  Cucumber for collaboration isn't the value
> for me.  I suspect that there are a *lot* of companies out there with
> one-person IT departments that may fit into my situation, and
> certainly a whole ton of personal projects where there was never any
> money or 'business case' in the first place.  In those cases,
> communicating features to "the customer" is just talking to oneself.
> It may still have value, but it isn't about teamwork.
>
> Anybody else in a situation like this?
>

In essence that describes my situation.  The difference being that I do
have a user (one) who will sit down and work through a feature (the
first time and then only briefly).  There are others who get to comment,
particularly on issues of nomenclature, but none that have the time and
inclination to make the sort of effort taken for granted in BDD.

I see cucumber as way to document my intentions and use the scenarios as
discussion points with others in my firm.  The great advantage is that I
can then use cucumber to drive what I call testing which, in turn,
drives coding. The resources do not exist to support much more than
that.
James B. (Guest)
on 2009-02-24 02:04
Stephen E. wrote:

>
> I'm the technology director for a non-profit academic society.  My
> organization has 15 employees.  I'm the one who knows anything at all
> about computers.  When I came on, I delegated *to myself* the
> responsibility of getting rid of our current excremental Web site,
> which is built on a lot of bad Microsoft ASP code and over 20 Access
> databases (I kid you not), and replacing it with something I could
> tolerate.  To me that means Rails or Merb.  I also decided that the
> features we offer should be totally reexamined, and we should make a
> site useful enough that our members come back frequently to support
> their academic work.  And I decided that if we're going to do this, we
> should do it *right.*  We should release it as open source and make it
> good enough that other societies can use it.
>

I occurs to me that you might find a look at Redmine
(http://www.redmine.org) worthwhile.  If not to use then at least for
implementation ideas and code examples (it is written in Rails).
Andrew P. (Guest)
on 2009-02-24 03:31
(Received via mailing list)
James,

If this is the case then to do BDD well you have to simulate the
dialogue
between customer and developer. At the moment you are so thinking like a
developer so you are starting with detailed technical features rather
than
general customer features. Also you're using such complicated language,
I
feel you really should make the effort to simplify right now.

One tip that might be useful is to be very clear with your language and
find
better names. If you need adverbs and adjectives to clarify your verbs
and
nouns, then your verbs and nouns aren't good enough.

Client is not a good name for an emphemeral role. If you need adverbs
and
adjectives to clarify your verbs and nouns, then your verbs and nouns
aren't
good enough. I'm not convinced that Entity is a particularly good name
either the fact that you need so many words to specify what it is =  bad
smell.

Now if you use replace Entity with Client, then you have Clients who you
represent. Each client has a history. The history consists of 'periods'
when
you represented them (haven't found a good word for that yet) 'term'
might
be reasonable but I'm sure there is some proper legal term perhaps
related
to contract. Anyhow use whatever resources you can and find single words
if
you can or hyphenated words if you really have to

 As for your features they can start super simple

Feature: Clients should have a history

Given there is a client
When I view the client
And I select history
I should see the client history


So now you can create your client, rails model with a name field and a
route. Create your history - probably could do this with just a route
and a
controller, and a view that says 'history'. Now iterate!

Feature: Client_Histories should have 'terms'

Given there is a client
When I view the client history
I should see terms


Iterate again

Feature: Terms should have starts, ends and one client

Iterate

Feature: Terms should be made dormant when ...

After each step you implement you think about the language and the sense
of
the thing you've just done and quickly review. If it doesn't make sense
refactor.

If you do this for the core things you have in your applications you
will
have something working and visual to then think about things like
authentication and feature organisation which you really want to address
only when you need to.

One of the fundamental ideas about Agile software is that each iteration
is
an opportunity for learning, because each iteration gives you feedback.
If
you do small iterations then you get back small chunks of feedback which
you
can learn from easily. If you do big iterations you get one big chunk of
feedback impossible to fully digest and most likely to be just ignored.

As you are mostly working on your own here you can get started now. Use
BDD
to explore your business domain and produce a stupidly primitive
(fundamental? foundational?) features and application, you might just
end up
with a firm foundation to build your application on.

Final tip, start with nouns, ignore verbs for as long as possible. e.g
think
about 'clients', but don't think about 'adding'. When you've got a whole
bunch of nouns together then you'll have enough context to make working
the
verbs much easier.



Seems I've gone on another 'rant'! Thanks for inspiring this James, I've
enjoyed thinking about these things, I can only hope they have some
value
for you.

All best

Andrew








2009/2/23 James B. <removed_email_address@domain.invalid>
Andrew P. (Guest)
on 2009-02-24 03:45
(Received via mailing list)
Stephen,

It appears that James situation is similar to yours which is very
different
to what I assumed. I've written a response (rant) about addressing his
problems in that context. Personally I still think that you have to
start
with fundamental customer produced features. As you and James are on
your
own you can meet your customer whenever you want, and you can produce
one
stupidly simple feature at a time. And for me that is cut and dry. As a
customer write a feature now, then as a developer implement it. Do one a
day, make them so simple that you can do one a day. By the time you've
got
your funding you'll have made a real good start.

If you put your project on Github you never know you might find come
other
people who can do one feature a day. You don't have to have funding and
grants to write open source.

I see Cucumber and BDD as fundamental tools improving the collobaration
between customers and developers. That doesn't change just because your
playing both roles. However their effectivness will be dramatically
reduced
if you don't actually play both roles!

All best

Andrew



2009/2/23 Stephen E. <removed_email_address@domain.invalid>
Stephen E. (Guest)
on 2009-02-24 06:52
(Received via mailing list)
On Mon, Feb 23, 2009 at 7:04 PM, James B. <removed_email_address@domain.invalid>
wrote:
>>
>> I'm the technology director for a non-profit academic society.  My
>> organization has 15 employees.
>
> I occurs to me that you might find a look at Redmine
> (http://www.redmine.org) worthwhile.  If not to use then at least for
> implementation ideas and code examples (it is written in Rails).

Thanks, James.  But at the moment I have no need for that level of
overhead.  Gantt charts are an anti-feature for me.  I'm effective
enough with my index cards and thumbtacks.  >8->



--
Have Fun,
   Steve E. (removed_email_address@domain.invalid)
   ESCAPE POD - The Science Fiction Podcast Magazine
   http://www.escapepod.org
James B. (Guest)
on 2009-02-24 17:11
Stephen E. wrote:

>
> Thanks, James.  But at the moment I have no need for that level of
> overhead.  Gantt charts are an anti-feature for me.  I'm effective
> enough with my index cards and thumbtacks.  >8->
>

I am sorry that I did not make myself clearer.  Redmine is far more than
a project management tool.  It is in fact a rather sophisticated, if
limited, content management tool that supports PostgreSQL as its back
end.  I was suggesting it as a potential candidate for your proposed
service to your end users.

Redmine handles multiple projects and and allows multiple project
specific roles for an individual (for example, a single user may be
manager of one whilst only a member of another).  You wrote of having
contributors post material and then maintain it. Well, a contributor
could be given their own "project".  This at a stroke, provides them
with a project wiki, public and private user forums, a file repository
and a notice board.  There is no need to have or to use issue tickets,
work flows, milestones or gantt charts at all.  On the other hand, some
collaborative efforts, or even a major monograph, just might find such
tools very useful indeed.

Redmine ties into git very, very well. The combination of the two could
provide a very thorough solution to the issue of revision control of
journal articles and books.

Redmine supports self registration.  Once a contributor is set up with a
project then the overhead of user administration can be, in large
measure, left to the individual contributor to manage.  A contributor,
as a project "manager", can grant specific capabilities to individual
collaborators.  A contributor can even set up sub-projects beneath their
main one.  This can be all accomplished without having to burden the
host organization with very much administrative detail.

Redmine's presentation is css based so that producing a customized skin
should be well within the capability and budget of even a very small
outfit.  With judicious configuration of Apache each project can be
reached by a distinct URL like project1.institute.org.

Given what you have revealed about your desire I think that it would be
worth your time to look at Redmine in this light.
James B. (Guest)
on 2009-02-24 18:19
Andrew P. wrote:
> James,
...
> Client is not a good name for an emphemeral role. If you need adverbs
> and adjectives to clarify your verbs and nouns, then your verbs and nouns
> aren't good enough. I'm not convinced that Entity is a particularly good
> name either the fact that you need so many words to specify what it
> is =  bad smell.
>
> Now if you use replace Entity with Client, then you have Clients who you
> represent. Each client has a history. The history consists of 'periods'
> when you represented them (haven't found a good word for that yet) 'term'
> might be reasonable but I'm sure there is some proper legal term perhaps
> related to contract. Anyhow use whatever resources you can and find single
> words  if you can or hyphenated words if you really have to
...
>
> Seems I've gone on another 'rant'!

I do not mind.  This is one of those "frank and useful exchange of
ideas" that I sometimes find myself in the office.  There is always
value in reading an informed opinion.

My situation is somewhat perverse in that I am converting an existing
system that really does not need conversion.  This system is now some 25
years old and it is still extensible and flexible enough to meet all of
the tax and trade regime changes of the past 20 years and foreseeable
future.  We are forced to convert because of a business decision of the
equipment vendor.

The choice of terminology is a difficult one for us because in this
industry many terms in casual business use, like client, have specific
legal import and attached liabilities.  The choice of entity was not an
easy one to make.  It was chosen mainly because all the alternatives we
could think of were worse.

You see, the law has this concept of a "legal person", but not all that
have standing in the courts are legally "persons" (not exactly true,
there has to be one or more actual legal persons somewhere in the
background but the idea is close enough).  There exist associations
(such as a partnership) that may conduct business, enter into contract,
and assume legal and financial responsibility for their actions without
themselves being a "legal person".  This is an issue for us.

Further, in our industry, it is a commonplace that an entity have
multiple roles with respect to our firm. A transport company for
instance may, at the same time, be a "client", a "vendor" and a
"provider".  Each of these roles possess specific legal and financial
attributes but, it is vitally important that the fact that these are all
the same legal entity be evident at all times.  It is also critical that
any change of status in one role does not obscure the existence of any
other.

As it turns out, this is one area our existing system does not do well
at all. We have separate clients and vendors there and we really have no
good way of tying them together for the same body.  We have virtually no
way of systematically handling entities that have no financial
relationship with us.  We cannot immediately tell if a current client
has been with us for 30 years continuously or was with us 30 years ago
and has recently returned.

A further complication is that we often deal with multiple incorporated
bodies of the same international firm.  Each of these has legally
distinct attributes but are nonetheless a single "client" insofar as we
consider them.

We have done the CRC thing, and we have had an awful lot (an AWFUL lot)
of discussion about the meaning of things.  The idea of client as role
evolved out of a great deal of discussion on what a client really was
(any legally distinct body that issues, or causes to have issued on
their behalf, instructions to us, that we accept, and that acknowledges
a financial obligation to us thereby).

What this comes down to is a simple "service for fee" but, there are a
vast number of corner cases in international trade.  There are whole
books written on just terms of sale.  There are marine insurance issues.
There are government security and tax agency issues. There are
international banking and payment issues.  There are consumer and
environmental safety issues.  Instructions can be issued on behalf of
clients by trucking firms, ocean shipping lines, airlines, warehouses,
consolidators, government bodies (both foreign and domestic) and law
enforcement agencies.

It is entirely possible for one of our clients to act as their own
"provider" (use of company vehicles for international transport).
Nonetheless, we owe a duty of care to our "client" to ensure that the
"provider" is properly instructed and authorized to conduct a movement.
A client may act as their own "supplier" as well (goods can  be shipped
from one division to another of the same firm located in a different
country).  A client may be the "producer" of the goods as well as the
"supplier", but a third-party logistics management company might be the
actual "shipper".  These are legally distinct, but financially related,
roles assumed by a single entity or its agents.  The distinctions are
important for us because, when we act for a client we act with power of
attorney.

It is confusing.  It is so because that is the business and regulatory
environment created by a myriad of government agencies, financial
practices, insurance regimes and transportation means.

And writing this stuff out helps sort out a lot of confusion, at least
for me.
Stephen E. (Guest)
on 2009-02-24 18:34
(Received via mailing list)
On Tue, Feb 24, 2009 at 10:11 AM, James B. 
<removed_email_address@domain.invalid>
wrote:
>
> I am sorry that I did not make myself clearer.  Redmine is far more than
> a project management tool.  It is in fact a rather sophisticated, if
> limited, content management tool that supports PostgreSQL as its back
> end.  I was suggesting it as a potential candidate for your proposed
> service to your end users.

Ahh, gotcha.  Thanks for the clarification.

It is an interesting idea.  I knew Redmine had wiki and forum
features.  I think I've probably been somewhat unfair to it because I
got the sense it was trying to be a better Trac, and Trac leaves a bad
taste in my mouth.  I know that's not rational, and I should give it a
real look at least to see if there are any good usability ideas worth
stealing.

If anyone cares, here's a loose and very wordy sample of my own
project thoughts and sensibilities from my blog:

http://extraneous.org/past/tags/malcontent



--
Have Fun,
   Steve E. (removed_email_address@domain.invalid)
   ESCAPE POD - The Science Fiction Podcast Magazine
   http://www.escapepod.org
James B. (Guest)
on 2009-02-24 18:39
Stephen E. wrote:

> It is an interesting idea.  I knew Redmine had wiki and forum
> features.  I think I've probably been somewhat unfair to it because I
> got the sense it was trying to be a better Trac, and Trac leaves a bad
> taste in my mouth.  I know that's not rational, and I should give it a
> real look at least to see if there are any good usability ideas worth
> stealing.

I moved from Trac to Redmine in March of 2008.  Redmine is nothing like
Trac in terms of implementation.  Or rather, so much more comprehensive
than Trac that comparison is invidious.
Andrew P. (Guest)
on 2009-02-25 18:51
(Received via mailing list)
James,

Thanks for taking the time and providing more fodder to chew on.

There are a couple of things I'd like to point out

Modelling the world is a futile and pointless task. Its to big and
complicated. Model YOUR world instead, choose the external boundaries
carefully and make your world as simple and small as you possibly can.

I'd question whether you need to give a monkey's about 'entity'. Whilst
it
maybe an essential concept in the overall legal framework that doesn't
mean
it has to be in YOUR world. If your software is about recording services
provided to some client and related payments. You can simplify - you can
just choose not to model all that legal stuff. If you model everything
you'll

1) Never write anything ... or
2) Create something so complex that nobody will ever be able to use it
...
or
3) Create something that just won't work

I think the major concept here is 'Account'. You service accounts.
Accounts
have clients. Accounts can be dormant or active. Accounts have
dormant_periods (and active_periods). Periods have starts and ends.
Active_Periods have activities some of which are charged. When an
account
becomes dormant all incomplete activities are suspended.

The complexity of clients, legal entities etc. doesn't help you get
paid. If
you really need to record it consider just using text. Client X is a
legal
blah servicing blah with blah blah ... . Humans especially lawyers are
real
good at writing and understanding that xxxx. When you can't get paid
because
you client modelling is to simplistic then revisit it.

Part of the point of BDD is to only do the things you have to do. To
justify
everything you do by proving it has specific business value. I've seen
in
some of your feature examples a classic BDD cop out - paraphrasing

Feature: Represent Legal Entities
In Order To: Reduce Costs
In Order To: Increase revenue
In Order To: Add business value

These are wooly justifications and a big BDD smell. With these you can
justify anything

In Order To: Reduce Costs
I should implement self relationships between clients so they can
provide
transport for themselves!!!

If you can't write a precise narrow and valid reason to do a specific
Feature you shouldn't be doing the feature. However finding and
expressing
these reasons is one of the hardest things to do in BDD. So its just
human
nature to cop out and write a wooly justification - after all we know we
need to do this Feature thats why we are writing it. But fundamental to
BDD
is to question every Feature we want to write and only write it if we
need
it right now and it gives us value now.

If you take this approach and use BDD from the beggining you will start
with
simple features

Feature: Accounts
In order to model the relationship between our company and our clients
We need accounts
So we can encapsulate the work we do in a seperate entity from the
client
itself

Hopefully the following will help

http://behaviour-driven.org/EnoughIsEnough
http://behaviour-driven.org/PowerfulQuestions

All best

Andrew



2009/2/24 James B. <removed_email_address@domain.invalid>
James B. (Guest)
on 2009-02-25 21:10
Andrew P. wrote:
> James,
>
> Thanks for taking the time and providing more fodder to chew on.
>
> There are a couple of things I'd like to point out

I will take a little time to digest this and perhaps to comment but, in
the meantime, thank you for your thoughts on this matter.  There is a
lot to consider here.
James B. (Guest)
on 2009-03-02 17:31
Andrew P. wrote:
> James,

>
> I'd question whether you need to give a monkey's about 'entity'. Whilst
> it maybe an essential concept in the overall legal framework that doesn't
> mean it has to be in YOUR world. If your software is about recording services
> provided to some client and related payments. You can simplify - you can
> just choose not to model all that legal stuff. If you model everything
> you'll

I have been mulling this over these past few days.  I now think that
what is wrong, besides having as yet only vague ideas of how this is all
meant to work, is that I am injecting too many implementation details
into the features and scenarios.  Whether or not a client is a
stand-alone design element or is dependent upon a superior element of
abstraction is really quite beside the point insofar as the presentation
of the system to the user is concerned.  I now believe that I should
just be writing down whatever it is that a client has to be in order to
satisfy the business requirements. If we need a higher level of
abstraction to capture other attributes then that should remain
invisible to the users.

Of course, realizing this issue and actually dealing with it are two
different things.  I will probably experience a great deal of difficulty
arriving at a balance between expression and implementation.
Mark W. (Guest)
on 2009-03-02 20:10
(Received via mailing list)
On Mon, Mar 2, 2009 at 7:31 AM, James B. <removed_email_address@domain.invalid>
wrote:

> Whether or not a client is a
> stand-alone design element or is dependent upon a superior element of
> abstraction is really quite beside the point insofar as the presentation
> of the system to the user is concerned.

I like to focus on that key word, "presentation," meaning what a user
sees on a screen or a piece of paper. The only truly important part of
a system is its physical output. Everything else is subservient to
that end.

Define an output ("customer balance on web page"). Define how to make
that happen, via a story/feature. Repeat.

///ark
This topic is locked and can not be replied to.