7

I have a domain expert to work with, but he would throws a lot of details to me verbally. The business logics are complex, business rules change often, the business process is long and multi-ending / intermediate wait-state. There are a lot of cases to deal with (because there are many states for the account, product and subscription).

What's the best way to deal with it? BPMN diagram isn't even low level enough to explain. Written documentations are time consuming to write and read. UML state diagram can become crazily complex very soon.

Any advice would be appreciated.

Henry
  • 289
  • 2
  • 10
  • 2
    First, tell him to slow down since you need to take notes or he needs to put it in writing. This is important and shouldn't be something someone rattles off the top of their head. – JeffO Sep 08 '11 at 23:31
  • I can tell him to slow down, but I wonder if there are any better tool/diagram I can use to capture the details clearly and easy to produce and clarify. Tried BPMN but it's slow and doesn't capture much details – Henry Sep 09 '11 at 01:28

5 Answers5

6

I would focus on use-cases and user-stories. I could document them, perhaps in a wiki, and give each one an ID (like UC00001). Then when I wrote unit tests and/or integration tests, I'd label them with the use case they inform.

Then when I get to two unit tests that can't both pass because they're mutually exclusive, I'd throw those two use cases back at the domain expert and have him/her reconcile them. That's the only way I can think of to keep it all straight.

Scott Whitlock
  • 21,874
  • 5
  • 60
  • 88
  • Good advice! The art in this would be.. the scope of the use-cases / user-stories. However, the down side seems like the architecture might be lost in the details, they're all in the code / test supplement by the wiki. Also, some process that needed to be manually handled might result in test cases that are always red (automation not implemented)..? – Henry Sep 09 '11 at 01:32
  • +1 for use cases. It sounds like the domain expert is brain dumping the business rules at random. He is probably over complicating the rules, and, the unstructured presentation makes it difficult to spot patterns and unnecessary steps. Stand back get the use cases nailed down, look for simplifications and repeating patterns. Then start designing. – James Anderson Sep 09 '11 at 07:43
  • This would be the analyst's job, as the domain expert doesn't seem to be paid to (or capable of) producing this type of analysis. @maple_shaft's voice-recorder suggestion would allow the analyst to perform this at a later time. – rwong Dec 06 '11 at 21:21
5

My experience working with extremely complex business logic and a domain expert is that the time of the domain expert tends to be extremely valuable, even more so in a small sized company.

He is of course rattling off endless details and nuances to you because it comes naturally to him for one, and secondly because he is likely an extremely busy person. These types of people don't like to have to repeat themselves.

I know this sounds strange but get a decent digital voice recorder like the kind a journalist might carry around with them. Have a sit down and just let him brain dump. While he is talking take notes but only write down the Main Points.

When you are done, tackle a single point at a time and replay the audio sections to recap all of the details that you missed. If you are not an aural person you can dictate the conversation into text or if your office has a secretary or administrative assistant that you are allowed to utilize then ask her to copy the conversation into a textual document for you.

This is the best way in my opinion and you will find that the domain expert will be much more clear and descriptive knowing he/she is being recorded, just make sure he/she is comfortable with this before you do. Further the weekends play havoc on your short term memory, you will come in on Monday and forget critical pieces of information forcing you to bug the domain expert with nagging questions that he has already been over.

Only then when you have the raw information can you formulate use cases and user stories.

maple_shaft
  • 26,401
  • 11
  • 57
  • 131
  • another great advice, thank you. So in your opinion once I have it recorded, what would be your next step other then coming up with a bunch of use case/user-story? Wiki? Test case? more analysis on system architecture? – Henry Sep 09 '11 at 01:53
  • 1
    @Henry, Putting the documentation you have assembled on a wiki is a good start. You can't come up with good test cases though until you have user stories and requirements. How to come up with these depends on who makes the decisions about WHAT they want the software to do. The Domain Expert might know the business, that doesn't mean he/she knows exactly what is required of software. If you feel you have good information then come up with high level software requirements. You can digest these later into more specific requirements or use cases. – maple_shaft Sep 09 '11 at 10:58
3

break it down:

  1. get general outline first and create a prelim design of the simple version

  2. then start adding complexities in line with business logic but keep the changes small and compatible with expected updates (but keep consistency always)

(this is a top-down approach)

shut the domain expert up and/or interrupt him regularly with questions/remarks if you need to. you can't help if you don't know what should be done

and business rules shouldn't be changing often, there is likely a scope problem if they do. see if that can be fixed

ratchet freak
  • 25,706
  • 2
  • 62
  • 97
  • That's one valid way of approaching (top-down..), but without the whole business logic/rules/process captured, I think it is not going to be very productive coding/designing something too primitive. – Henry Sep 09 '11 at 01:26
1

You appear to have a very complex task at hand, and need to treat it with the respect it deserves. Are you sure you don't have a tiger by the tail thinking of it as a domestic cat. The outcome of such a mistake is fairly predictable.

The documentation will take a while because its a big complex job requiring complex documents. The UML gets complex and hard to understand because the job is complex and hard to understand. The job needs to be treated as a big complex job, until proven otherwise.

Therefore my advice is start by 'employing' a Project Manager and a Business Analyst. If you are 'it', put away you compiler and read a book on the above two jobs and perform those roles, before being a software developer.

mattnz
  • 21,315
  • 5
  • 54
  • 83
  • Project Manager & Business Analyst, right, but I guess one of the multiple hats a developer need to wear for a small size company. – Henry Sep 09 '11 at 01:21
  • Any technique I can learn to document "big complex jobs"? – Henry Sep 09 '11 at 01:30
  • I have always been hopeless at documents, wanting to dive into get the job (code) done. Best advise I can think of is if you find youself thinking in terms of code, data and algorythms, and you are still changing or defining requirements and design, the words used by pilots can be useful "Pull Up, Pull up". Try to think one level higher until you have it clearly documented, then move down a level. – mattnz Sep 10 '11 at 07:20
1

I think that this is not unusual. All the litrature in requirements gathering can qualify for an answer here but you can see this elsewhere of course.

On a high level, I would approach the problem this way:

  1. Clearly identify the problem at hand.

  2. Define objective of the system.

  3. Now you have a scope to work with. Identify the main business processes.

  4. For each business process in scope, define: inputs, outputs, actors and business rules (pre conditions, post conditions, rules, exceptions)

  5. Use BPMN to document essential business flow from a business perspective to show how processes relate

At this point, you have documented your understanding of the business. Confirm it and Proceed from this point with your software design to solve the problem.

Time spent on analysis is well worth it.

NoChance
  • 12,412
  • 1
  • 22
  • 39
  • I guess there are just too much details to capture and I have not found the right tool to do so. Each edge of each state has many outcomes. I wonder if there are better tools than basic flow chat / UML state diagram for that. – Henry Sep 09 '11 at 01:23
  • 1
    When the logic is complex, no diagramming technique that I know of could help. Try Pseudo Code. It is simple to read, write and it is not technical so your business people can understand it. The state of an object changes within a process, so state changes are part of the system response to events - All this can be captured in Word or Excel. The thing is, don't just depend on UML diagrams alone. – NoChance Sep 09 '11 at 02:13
  • 2
    Also, truth tables are good method to simplify complex logic. – NoChance Sep 09 '11 at 02:47
  • Thanks again for your valuable answer... Truth tables? That sounds old school, how much would it help and what is it effective against? – Henry Sep 09 '11 at 04:53