About Data Flow Diagrams

[Kate Stout <stout -dot- k -at- comcast -dot- net>]

While I'm not sure I buy into Tony's "DFD's are the best" level of 
commitment, I think using analysis techniques to describe the systems 
you are working on has great value.

I worked at a company back in the 80's that had tools for creating 
DFD's, State diagrams, and other analysis tools, for designing software 
and real-time hardware systems. These techniques are now also seem in 
the cluster of analysis techniques used in UML. I've found that any 
attempt to describe the system in a structured way helps in the 
understanding of the functionality, possible issues and interaction 
patterns. The techniques can be applied at the end-user or software level.

Ideally, the systems analysts and systems designers are using some 
appropriate set of these techniques to figure out what they should be 
building and how they should be building it. In reality, they often 
don't have the time or the management support to do so. (In fact, does 
anyone remember the job of system analyst? Someone who figured out the 
what before figuring out the how?) So having a writer do this analysis 
for all or some parts of the system has merit. It helps to clarify 
interaction, and it may clarify design issues.

One thing to realize about the analysis techniques is there are a lot of 
zealots out there. For example, I've been involved in 3 hour discussions 
about whether a 1-to-many relationship in Data Model Diagram should be 
represented by a line like this
----> or this <---->>.

I recommend avoiding those fights (do whatever the locals do), and find 
techniques that work for you. Here's some techniques I find useful.


Use cases
----------
A task a user will perform using the system.
http://www.agilemodeling.com/artifacts/systemUseCase.htm (note that 
this one is done textually)
http://www-106.ibm.com/developerworks/java/library/co-design5.html

These most closely relate to end user documentation - What are the steps 
the user performs to perform the task.

Data Flow Diagrams
------------------
How data (information) will move through the system
http://www.agilemodeling.com/artifacts/dataFlowDiagram.htm

Data Model Diagrams
-------------------
The relationships between data components.
http://www.essentialstrategies.com/publications/modeling/chen.htm

Most useful when developing APIs to ensure that your objects are 
consistent throughout the system, and to give the user(a programmer) 
what the relationships are.

State Transition Diagrams
-------------------------
How status (state) changes in the system. Imagine a banking system where 
your account status changes based on various events (adding money, 
paying out money... etc.)

Bastardized Flow Charts
-----------------------
I never really do all the details/paths of a flow chart, but they can be 
very helpful in providing an overview of how things work.


Regarding tools
I'm in favor of doing first drafts on paper, or on a whiteboard. In fact 
one of the most powerful things you can do is give a quick explanation 
of the notation you are using, and do the first couple of bubbles of a 
diagram, and then hand the pen over to one of the team members. 
Suddenly, they are in control.

I like to then transfer the rough drafts into a drawing tool - I've used 
everything from specialized design software to Visio, to Powerpoint. I 
think it's useful to get the picture into a format that it becomes easy 
to manipulate. From there it's easier to circulate and make changes. In 
one place I worked, they actually checked these into the source control 
system as parts of the design documents. I can also use these, in a 
simplified/prettied up form in documentation, white papers, etc.

For me, this is also a comfortable thing to do - I can make most drawing 
tools do what I want (especially if I keep it simple.)

True Story
I was working on a contract for a company that had a product that was 
very hard to use. They had designed it in such a way that it exposed a 
lot of the details of the database structure, rather than using a task 
orientation. The target user was a shipping clerk, so there was a huge 
mismatch.  In order to understand one task, I ended up drawing a simple 
data flow diagram. This started out as a way for me to understand 
things, because it was a very complicated product. By drawing it I 
realized much better how things worked. In fact, things became so clear 
to me that I thought it would be helpful to put a simplified version of 
the DFD into the end user documentation. I added some simple colors to 
the diagram so that it fit in with the book design, removed a couple of 
the more obscure paths, and put the picture in the book.

The VP of developement showed up in my cube a couple of days later, 
demanding to know who had told me to do this. He seemed very angry, and 
I thought I was in deep doo-doo. So I told him my story. He then said, 
"Do you know, this is the first time it's been clear to me how this 
works? And I now realize that we've got a serious problem if <a certain 
set of events> occur in the system!"  He then asked me to show the other 
writers some of the analysis techniques, and we started using them in a 
simplified way in the documentation of complex tasks.

So to me, there's merit in the approach. But as in everything, a bit of 
moderation is useful. I don't buy into one technique, or one tool. As is 
the case in most of what we do, it's really about effective 
communication. If your technique and tool match your groups needs, then 
you've got a useful approach.


Kate

-----------------------------------
Kate Stout Consulting
Making it clear...
Technical Writing and Training
http://www.katestout.com
stout -dot- k -at- comcast -dot- net
------------------------------------


^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

ROBOHELP X5: Featuring Word 2003 support, Content Management, Multi-Author
support, PDF and XML support and much more!
TRY IT TODAY at http://www.macromedia.com/go/techwrl

WEBWORKS FINALDRAFT: New! Document review system for Word and FrameMaker
authors. Automatic browser-based drafts with unlimited reviewers. Full
online discussions -- no Web server needed! http://www.webworks.com/techwr-l 

---
You are currently subscribed to techwr-l as:
archiver -at- techwr-l -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- techwr-l -dot- com
Send administrative questions to lisa -at- techwr-l -dot- com -dot-  Visit
http://www.techwr-l.com/techwhirl/ for more resources and info.