The Design of Software (CLOSED)

A public forum for discussing the design of software, from the user interface to the code architecture. Now closed.

The "Design of Software" discussion group has been merged with the main Joel on Software discussion group.

The archives will remain online indefinitely.

Ubiquitous language: Means of communication

Hi all, as a non-native English speaker, I find it sometimes extremely difficult to find "correct" names in my domain model. I am normally using for example Word and web to find synonyms when in doubt but sometimes I come across an entity that I just can't find a name for.

My question is in two parts:

1) Do you have some suggestions for my specific problem: A business has "means of communication", for example email(s), phone(s), fax(es), telex(es) etc. In my domain I am calling this group "Communication", but I just can't find a nice common name for every "Communication Item". Thus for now they are called "CommunicationItems"... Have some of you a good suggestion?

2) What kind of tools do you use to define your ubiquitous language? Some great website suggestions or something else?

This is a problem that maybe doesn't sound important, but I feel when we have many people (developers, managers, clients) involved in a project a single bad name can cause a lot of confusion, e.g. lost time.

Cheers,
Miika
Miika Mäkinen Send private email
Saturday, January 12, 2008
 
 
a) If you're talking about a type of communication then perhaps a "[communications] medium" (plural is "media") or "[] channel"; or "[] device" if you're referring to an instance of the machine on one end of that channel.

b) I use a thesaurus, or "define:" with Google for example http://www.google.ca/search?hl=en&q=define%3Amedium
Christopher Wells Send private email
Sunday, January 13, 2008
 
 
I use thesaurus.reference.com and dictionary.reference.com and occasionally a Danish-to-English dictionary (My native language is Danish), if I know a Danish word that covers the concept. Usually, I find it equally hard to find the most precise term in English as in Danish. I think the reason is, that narrow technical literature is usually not available in Danish, so in certain domains, I'm actually better versed in English, than in my native tongue. This is probably more explicit, since Danish is a very small language; I reckon it will be easier to find translations in French or German.

> This is a problem that maybe doesn't sound important,
> but I feel when we have many people (developers,
> managers, clients) involved in a project a single bad
> name can cause a lot of confusion, e.g. lost time.

I think most people would agree, that choosing proper names, is an important part of writing good software. Doing so may be slightly harder, when the language isn't your native, but that doesn't mean that it's easy for someone speaking English natively. In fact, I would say that even if you're native speaking, you should look central terms up in a dictionary. Words can easily have certain connotations or etymological meanings, which you weren't aware of.
Troels Knak-Nielsen Send private email
Sunday, January 13, 2008
 
 
#1 tool for writing ubiquitous language: your customer!
Mike Stockdale Send private email
Sunday, January 13, 2008
 
 
I guess I'm (again) looking for an easy way out when there isn't... :)

I am using same tools as you guys (especially google "define:"). About my specific issue, I think I'll go with "Communication Line" (it's a business directory)... "Medium" while perhaps correct, it seems to be too difficult for client.

Thanks for all the input! I also appreciate there are other people who value the naming, as I find that I'm sometimes perceived as a perfectionist while stuck on this kind of issues!
Miika Mäkinen Send private email
Sunday, January 13, 2008
 
 
Be careful of using a term that has a generally-accepted definition that is at all different from your definition.  People will figure that they know your definition without considering that it might be different.

I have come up with a number of terms that are used in the in-house client billing system that I have developed.  These can be long, so sometimes, I also come up with an abbreviation.  Thus, we have:

* Definitions
* Last Modification: 2007-06-27
*
* WO (Work Order):
*      usual non-CBS2 meaning.
[CBS2 is the name of the system.]
*
* GWO (General WO):
*      a WO used as a catch-all for work that is not otherwise specifically
*      assigned to a WO of its own.
*
* GWOI (GWO Invoice):
*      an Invoice generated from a GWO.
*
* SWO (Specific WO):
*      a WO that is not a GWO.
*
* SWOI (SWO Invoice):
*      an Invoice generated from a SWO.
*
* WOI (WO Invoice):
*      an Invoice generated from a WO.  A WOI is either a GWOI or a SWOI.
*
* WCC (Work Classification Code)
*      a code used to distinguish what sort of work is being done.  It can
*      not be totally numeric.
*
* Functional/Detail/Contract WO
*      a WO with the appropriate invtype.  Functional WO is abbreviated
*      "FWO".
*
* Invoice Type
*      An invoice can be a Detail Invoice, a Contract Invoice, or a
*      Functional Invoice.  This is determined by the WO (cwko.invtype).
*
* Detail Invoice
*      A Detail Invoice is a run-of-the-garden invoice.  In an invoice, the
*      details of the the transactions are consolidated.  All transactions
*      contribute to the dollar amount, but WFC with a wfctype of "F" are not
*      allowed.
*
* Contract Invoice
*      A Contract Invoice has the same invoice format as a Detail Invoice,
*      but WFC with a wfctype of "W" are not charged.  These uncharged
*      transactions are kept, so that cost analysis can be done.
*
* Functional Invoice
*      A Functional Invoice is charged the same as a Contract Invoice, but
*      has a different invoice format that combines elements of the more
*      general invoice format and the Work Order Activity Report.  For this
*      invoice type, a Work Order Activity report is not printed during
*      invoicing.  A Functional Invoice does not have any consolidation of
*      transactions.  (Since the intent is that only a few select
*      transactions (Functional-level ones) will be printed, this is not the
*      problem that it casually appears to be.)
*
* General Invoice:
*      (obsolete) an invoice that is not derived from a WO.  For these,
*      catx.wonbr (a column no longer extant) was 0 and catx.trntype was
*      "IN".  Abbreviation (in code): GenI

Sincerely,

Gene Wirchenko
Gene Wirchenko Send private email
Monday, January 14, 2008
 
 
also check standards like OASIS <www.oasis-open.org> for example ebXML, UBL.

wikipedia can also generate lines of enquiry.
John Griffiths Send private email
Wednesday, January 16, 2008
 
 
> as a non-native English speaker, I find it sometimes extremely difficult to find "correct" names in my domain model.

The problem isn't unique to non-native English speakers :)

Friday, January 18, 2008
 
 
This is a tough question debated for decades in computer science and areas of philosphy as well. Solution is to build standards. One such effort is led by IEEE and the standard is called SUMO (Standard Upper Metadata Ontology).

For common users of English language, there exists a mapping from words in wordnet (huge lexical collection) to SUMO classes and properties. You can explore this mapping at following website:
http://sigma.ontologyportal.org:4010/sigma/Browse.jsp?kb=SUMO&lang=EnglishLanguage

I find mapping to be good for proper english words like phone and fax. You will find these map to classes that are subclass of CommunicationDevice. However, in you want to represent attributes of these concepts, e.g. phone number of fax number than you may not find a predefined mapping. In this case, you may want to define you own concept which combines the attribute with the class name. In your example, it may be called CommunicationDeviceAddress.

I hope using above mapping mechanism will help you give more consitent names to your classes and variables.
nayan j Send private email
Saturday, January 19, 2008
 
 
Great stuff, both oasis and sigma seem invaluable resources.
Miika Mäkinen Send private email
Friday, February 01, 2008
 
 

This topic is archived. No further replies will be accepted.

Other recent topics Other recent topics
 
Powered by FogBugz