We are working on standardizing our Bugzilla application across all projects. The default installation has bugs grouped into Products which have Components and Versions.
We are united in our definitions of Product and Version but there is still some confusion/discussion/argument about what constitutes a Component.
How would you define a Component as far as it relates to classifying bugs in a project?
For bug tracking purposes, I would use Component to represent high-level areas that different developers tend to handle. For me, Component [in bug tracking] == Area of Concern.
For example, for a fictional EventPlanner application, I would list my components as:
Calendar
User Interface
Printing
Note that this may be different than what I, as a developer, would typically consider a software component. For example, my EventPlanner app might have use Calendar API, but "User Interface" and "Printing" themselves are not software components.
A component is a subdivision of a product and it provides a subset of the functionality of the product.
For example, if Stack Overflow is the product here are some potential components:
Questions
Tags
Badges
Profiles
A bit of glue logic should piece the components together to form the project.
I would define Component similar to referencing a branch of code like a project within Visual Studio which could be a class library, console application, windows application, or website/web application.
A good definition that will serve your purpose.
Anything that's a "helper" object, something that does something small to support the larger functionality of the application, and can be reused in other Products.
For example, an EmailSender class, or an ErrorLogger, etc.
Whatever it is you're most interested in breaking down your Products into for purposes of bug tracking. It's more important that the distinction is useful to you than it be "correct" according to some concept that's not specific to the problem of bug tracking.
To me, any part of the code for which you can change the implementation without breaking other parts could qualify as a component. Something you can definitively point to and say, "This bug is there, and nowhere else."
If your product is a giant spaghetti code ball, you might not get any benefit from components. If you've decoupled very well, and you have a very large project, you might have hundreds of things that could qualify as "components", and you'll probably have to semantically group them to prevent the distinction from being more trouble than it's worth.
EDIT: In response to a comment on another answer, this model works best if the person filing the bugs has the necessary knowledge of the problem to do the filing. We always review (triage) reported bugs and file them ourselves. If you're leaving component selection up to the users, this idea won't work very well for you.
Dr. A. Richard Newton from the University of Berkeley who teaches a course called "Component-Based SoftwareState-of-the-Art and Lessons Learned" defines a software component as
A software component is a unit of
composition with contractually
specified interfaces and explicit
context dependencies only. A software
component can be deployed
independently and is subject to
composition by third parties
I dont think there is a better definition. So bug here could be at component level or at interface level i.e. composition level.
Related
I'm a student of software engineering. My lecturer of "Software Architecture and Design" has told us that we can generate source code from all the UML diagrams (or most).
I already can / have generated code from class diagram. I'm unable to generate code from other diagrams.
Do I have to someway connect those diagrams with class diagrams to do that?
This is simply nonsense. You can not generate code from any diagram at all. You can however generate code from a UML model. This can (but not must) have a couple of diagrams to help visualization for humans.
Now, code is related to classes. That means you need at least some classes defined in your model. A use case helps understanding why classes will do things they are supposed to do. But in no case can you create code from a use case.
There are other model elements which help support creating more detailed code. Those are e.g. state machines which can translate into equivalent code sections.
Activity and sequence diagram also help visualizing how certain code sections run during execution. But you will not (seriously) use them to create code.
Yes, you can, but it's not as simple as what you're describing. Model-Driven Architecture is an active area of research right now, but it hasn't really "caught on" yet. Its proponents argue that it allows for a higher level of abstraction in much the same way that C offered a higher level of abstraction than assembly language and Java offered a higher level of abstraction than C. I think that this could be very useful in the future if they can get the tooling right.
Actually, this isn't even an entirely new idea - the idea of graphical programming in general (which, if you think about it, is basically a generalization of UML-derived programming) has been around at least since the 1980s that I know of (and probably a lot earlier). In fact, Frederick Brooks Jr. talks about it in No Silver Bullet – Essence and Accident in Software Engineering (which was originally published in 1986 and appears in current editions of The Mythical Man-Month):
A favorite subject for Ph.D. dissertations in software engineering is graphical, or visual, programming, the application of computer graphics to software design. Sometimes the promise of such an approach is postulated from the analogy with VLSI chip design, where computer graphics plays so fruitful a role. Sometimes this approach is justfied by considering flowcharts as the ideal program design medium, and providing powerful facilities for constructing them.
Nothing even convincing, much less exciting, has yet emerged from such efforts. I am persuaded that nothing will...
His argument was that, at the time it was written, the tooling just wasn't "there" yet; for example, screen sizes were notoriously small. Also, the flow chart is actually a really bad design mechanism. Also,
More fundamentally, as I have argued above, software is very difficult to visualize. Whether we diagram control flow, variable scope nesting, variable cross-references, data flow, hierarchical data structures, or whatever, we feel only one dimension of the intricately interlocked software elephant. If we superimpose all the diagrams generated by the many relevant views, it is difficult to extract any global overview. The VLSI analogy is fundamentally misleading - a chip design is a layered two-dimensional object whose geometry reflects its essence. A software system is not.
I'll leave it to you to judge whether or not you agree with him or whether this still applies.
So, to summarize: yes, it's at least theoretically possible, and there have been considerable efforts to generate code from UML diagrams, but you'll need multiple diagrams to generate much more than basic class structures and method stubs. It's not like you can write a use case diagram, press a button, and magically have a complete software system.
I think I have found the answer. We can generate code. Say I have a "use case". I right-click on it. Go to "advance" and select "instance classifier". Over there I can actually make my "use cases" , "sequence diagram objects" etc the instances of an already created class or I can even create a class right over there.
I often draw a dataflow on a sheet of paper. Even the planning of my little tools is done on a paper.
There exists UML.
The problem is - I don't like it. All the tools I've used (Visio and a lot of online editors) are just not flexible for my hands. With a pencil you can easily draw shapes and connect them, describe them.
What could you suggest in order to create a diagram of data-flow, sequence diagram, etc. in the fastest, most natural and easiest way except on the computer not the paper :)
****Useful links as posted in comments:** SO Link #1 SO Link #2
Right now I am curious about 2 things and one of them was in my minds quite long ago:
1) Mindmap - I've tried a while ago, quite liked it but abandoned. Hoever will give it another try
2) Whiteboard. It would be the easiest and most natural method, except that taking a photo and storing it somewhere on a computer would make the process repetitive and boring.
Has anyone other interesting ideas? I would really like to hear what others are using to design their software and the progress of it.
Thanks a lot!
Why do you want to hand-draw the UML at all whether it's on paper or on the computer?
I agree that you need a model to represent the design. But even in large projects of about 500 man-months, I observed that only 3-4 sequence diagrams really matter and have a chance of surviving the entire lifecycle of the application. Those 3-4 sequence diagrams (and class diagrams that represent their static time relationships), usually represent the high level design of the application.
Or, look at it this way:
Any decent enterprise application will not have 20 different call flows. There will be one or two generic (or abstract) call flows, which all the concrete use cases implement. Let us take a simple Struts / EJB application. The generic flow will be something like - an action class calling a validator and then calling a stateless session bean, which in turn calls a domain class, which will call a DAO. All the use cases of the application just implement this flow with concrete classes that are specific to that use case.
Do you agree?
If you do not, I would like to hear about applications that have 20 different call flows and survived for 5 years after the first release.
If you agree with me, we are boiling down to 3-4 class and sequence diagrams even for large enterprise applications comprising several thousand classes. Why is it a big deal how you draw and maintain those 3-4 diagrams?
You might say that you want to document all the use cases for training or documentation purposes. During my last 14 years of experience in the real enterprise software world, I don’t remember seeing well 'maintained' UML documentation. First of all, good documents are difficult to produce and are not found that often. Secondly, they are out of sync with the code most of the time. Most of my experience is with large banks, insurance companies, Auto companies, etc. Those environments are just too hectic and their resources are limited (really? Are we talking banks? Yes, difficult to believe, but true) for 'maintaining' good documentation.
So am I suggesting that we get rid of UML?
No. We need visual models to represent complex systems. Human brains seem to be at their best when processing visuals. The visual cortex, which is responsible for processing the visual images, is the largest system in the human brain.
So what is a reasonable solution to easily produce and maintain UML models?
Probably we are better off using the current crop of UML tools to draw those 3-4 high-level UML diagrams. If you hate using them, check option 3 below.
For the diagrams at the next level of abstraction (any useful models should have different levels of abstraction), generate the UML from source code. You can generate both class and sequence diagrams.
In this age of agile methodologies, why not just write the shell classes and generate those 3-4 high-level UML class and sequence diagrams as well? This way there won't be any UML to maintain at all.
The source code is the truth.
Can you argue against that statement? If not, why not generate the models from the source code itself? I am not suggesting the round-trip engineering, by the way. I am just suggesting a one way trip - from code to models.
There are 2 main problems however with the generated UML.
When we hand draw a class diagram, we show the relations between the classes involved in a scenario. Most existing class diagram generating tools allow the user to drop the Java classes (the source code) into the tool and the tool automatically shows the relations between the classes. The problem here is, how does one know about the classes involved in a scenario to begin with?
The second problem is the verboseness of the generated diagrams. There are tools available to generate runtime sequence and class diagrams for a scenario. But the diagrams are often very verbose and defeat the purpose of models, whose purpose is to highlight the important aspects and filter out unimportant details.
Good UML generating tools should address both the above problems. There are a few tools in the Java domain that try to address these problems. Check the discussions below:
What tools should I use to visualize structure of my code
Are there any tools for detecting architectural and design patterns in code?
I hope I answered the original question:
Has anyone other interesting ideas? I would really like to hear what others are using to
design their software and the progress of it.
I am the author of the runtime UML generating tool MaintainJ, but I tried to address the original question in an objective manner. Your comments are welcome.
There are various tools that allow you to create diagrams based on textual input. There's some up-front learning in that you need to learn the syntax. However it's not hard to do. Once you have, creating diagrams can be very fast. There are some downsides; in most cases there's limited ability to change the layout/style. Significance of that will depend on whether you like their style or not.
There's a growing number, here's a few you might want to look at:
UMLet: desktop app, supports most UML plus various other diagrams. Can also create your own custom shapes & connectors. FOSS.
WebSequenceDiagrams.com: online sequence diagrams.
TextUML: desktop app. Focus is executable models, auto-generates class diagrams. FOSS. It also has an online commercial sibling.
hth.
I like using a whiteboard and a camera. For even more flexibility, use post-it notes on the whiteboard.
I use ER diagrams (on the whiteboard) to model my data, and message sequence charts (on the whiteboard) to model the data flow. I'll also do quick mockups of UI pages on the whiteboard.
Asides from that, I use Ruby/Rails to code server side and HTML/CSS/jQuery/JS on the client.
If even Visio is not flexible enough, I'd suggest a digital whiteboard or touchscreen with a whiteboard software. After some accommodation you could probably use a simple tablet (without display) as well - they are really cheap.
Regarding pure software: we are trying to achieve a "pen-like" input method with UML Lab, but it currently supports Class Diagrams only...
I think that the UML and code should be mixed using a class diagram. You model your architecture with the class diagram (e.g package, classes etc....) then you code your business finally multiple iterations between code and model.
I think that UML should more be oriented to code but not to focus on textual input.
The problem with standard languages, such as UML, is that you have to invest a considerable effort to learn the language and the modeling tools. These languages are defined by an expert consortium, e.g. OMG, that proposes a language specification suited to the biggest overlap of design problems in a certain domain.
Why not defining your own language that fits exactly to your needs and your specific problem? Such languages are termed Domain-Specific Languages (DSL). Instead of investing into learning a language that's complex, you invest into the definition of a languages that exactly suits your needs.
There are numerous approaches that support the definition of DSLs. The most widespread is the Generic Eclipse Modeling System (GEMS). Personally, I made great experience with GrGen due to its versatility and the possibility to automate working steps using graph transformation.
No. There are various other ways. UML is just an option.
Pen and Paper Prototyping is a great option too, it doesn't have to follow UML.
Mind Map is another great way.
For more adaptive software processes, UML use is encouraged to be as minimum as possible. Such as, teams that practice Agile or XP tend to use UML less and they would rather rely more on informal means to conceptualize the software. In a rigid structured company, UML can be rigorously followed.
Today we had a discussion at the office about UI elements in the required document.
The question is whether a UI requirement is functional or non-functional.
"the background must be blue"
Is this a functional or non-functional requirement?
That is a non-functional requirement, it states how a system is to perform, not what it is to perform.
If this clear distinction is too black and white, too simple perhaps, ignore it or provide a better one ! And, why do you care ?
EDIT: prompted by the other answers. Whether the requirement is functional or non-functional is immaterial to its requirementhood -- if it's a requirement you'd better satisfy it in your product.
When looking at the two definitions as given by Wikipedia, I would say neither.
a non-functional requirement is a requirement that specifies criteria that can be used to judge the operation of a system, rather than specific behaviors
a functional requirement defines a function of a software system or its component
The color of the background is not a specific function or behavior of the system and it also can not be used to judge the operation of a system.
I think that these kind of UI requirements do not need to be specified at the beginning of a software design cycle. What if during development you find out that the wrong type of blue was described? These choices are not requirements, but need to be sorted out during UI development (preferably with a user group to judge).
I am currently struggling with accessibility requirements for a customer.
The fundamental need is to support users who are partially sighted and blind. The former by careful selection of fonts, colour contrasts etc. The latter by keeping HTML very simple so that an application can parse it and convert it to speech or braille.
So I would say that details of presentation are worthy of specification.
I would also say that screen layouts, exactly what data to display are indeed functional specifications and by extension the colour schemes are part of that.
Definitions like this differ depending on the organizaton. Unfortunately, there's only generally accepted practices, and the distinction between funcitonal and nonfunctional or the "what" and the "how" are usually a lot more subjective than most people realize. To a UI designer, corporate standard color schemes could very well be the "what" and not the "how".
I would call this a UI specification, or to be more precise, a UI spec requirement. That's not a standard term, but sometimes you just need to be more specific to avoid confusion. You might have a nonfunctional requirement saying to follow corporate guidelines, and then put the UI spec requirements in that guideline.
Sometimes the frontier is fuzzy. But in this case I would clearly say non functional. Functional is a core business requirement, independant of technology, ergonomy, something that must be there if you change the UI. Color is about UI except if it represents something special to business.
The performance improvement in the UI is also one critical non functional requirement which can be measured. Caching the static master data, using ajax calls to partial submit (instead loading the entire page), and loading heavy javascript or css files initially will certainly improve the performance at the UI layer. Back ground may not be considered as an NFR.
Closed. This question does not meet Stack Overflow guidelines. It is not currently accepting answers.
Questions asking us to recommend or find a tool, library or favorite off-site resource are off-topic for Stack Overflow as they tend to attract opinionated answers and spam. Instead, describe the problem and what has been done so far to solve it.
Closed 9 years ago.
Improve this question
As part of an assignment, I have to create a component diagram for existing code. I understand what a component diagram is and the information it presents, but I'm not sure of a process to follow when looking at code to diagram it out to produce a component diagram. I'm also not sold on how a component diagram, if I am presented with one, would help me with implementation of a system.
Maybe have a look at Scott Ambler's UML 2 Component Diagramming Guidelines and Introduction to UML 2 Component Diagrams. These are IMHO two good resources that explain how and when such diagram can be used.
You state two separate concerns: how to get from code to diagram, and how to use one as a guide to implementing a system. If you're diagramming existing code, I don't think the second question applies.
If you're designing new code, then a component diagram can be 1) a useful abstraction to understanding the important parts of the code, minus all the distractions, and 2) a good way to communicate to others.
If you're looking at existing code, then an existing component diagram (or one of several other UML artifacts) can be a guide to the code, which especially helps in maintenance: it can be easier to identify the location of bugs, major class responsibilities, etc.
If there's no diagram, then the exercise of making one by reading code is a good way to familiarize yourself. I've done this in a number of cases when inheriting a complex codebase. As a result, I have a couple of pages of diagrams of the application and database that tell me at a glance the interesting things about its major components. At any given time, I'll be very familiar with some areas and not others, depending on what I'm working on. The diagrams are a good reminder of how to use various parts of the application. And they're helpful when bringing others onto the team; they understand the code much faster after a half-hour walk through the diagram.
To work from existing code, you'll need to read through it, identify the major classes in use, and trace back to understand the dependencies and the interfaces, method signatures and data structures they use to collaborate. If it's a database-backed app, it can be helpful to see a description of the DB, as it should embody the main concerns of the application.
It helps to have some use cases to guide the investigation, since with event-driven applications you need to understand what the user is doing in order to trace through the code. If there are no existing use cases, then start by writing some simple high-level ones yourself. Then go through the code by use case, and identify the major objects in use. Hopefully, you'll find major classes in the program to macth the major use cases you identify. E.g., if the application is a web-based e-commerce app with an administrative user-interface, then you'll identify a number of end-user and administrative-user use cases, and should expect to see some classes specific to each of those families, as well as generic and utility classes used throughout.
Stay at a high level, avoid the temptation to account for every single thing you encounter.
As Pascal said, Scott Ambler's a great resource of practical UML knowledge, and has guildelines that can be used as little or as much as necessary. Specifically, see Introduction to UML 2 Component Diagrams. Hoever, he's writing much more for people designing new code than those documenting existing code, so you have to adapt some of what he discusses.
Martin Fowler's "UML Distilled" is still the best book on UML you can get. Its chief virtue is that it's thin - densely packed with info.
For me UML isn't primarily about helping me to design a system (though it does help). It's about helping me to communicate the design to others by giving us a common language/notation.
It makes the conversation easier so we don't waste time trying to translate between our different frames of reference.
The Scott Ambler is another good off-the-shelf standard answer. However, in the case of component diagrams I find the suggestions under (Section Creating Component Diagrams) fine, but long and not relevant to your documentation needs. From Scott's list (Creating Component Diagrams) I would really focus on just (1, 4, 5, 13), as many of the suggestions are design best practices. I will add some more of my own below.
Martin Fowler's book is great in many ways, but not really in depth for Component Diagrams or Co.. A massive 7 pages, which shows you where it was prioritized during his writing, as class diagrams get 18 pages or so.
I agree with you that you should be able to realize when to use a UML diagram. The UML 2.2 Specification itself says that it was built for Component (Service/Interface) Oriented systems. Taking a basic MVC GUI app and pushing into a Component diagram/model really does not make sense. There are also a couple ways of diagramming the component relationships, Scott Ambler's site shows them in Figure 1. For large multi system implementations I have found these diagrams very effective, e.g. lots of interfaces and lots of abstraction of systems.
My Suggestions: (I use components for modeling often, and I read the UML spec on this stuff)
Skip using ports for the HL component diagram, they are for grouping and although they look fun in Scott Ambler's diagramming you do not gain a lot for the effort.
Avoid getting caught up in an internal Component Structure. Only do this if clarity is needed for a high level of complexity.
Don't slip into making most "classes" into components.
Focus on the interfaces and where real boundaries exist, clues are public interfaces, package groupings, WSDL, external system interactions.
For your first several I would start top down. First make one of all the external system interactions, then do the next level down, use ports and composite structure if you want, but I don't like them, they are messy because the composite structure are actually Parts, a UML object that is an instance of a class or component, the naming get complex etc.
Pick one notation in general, use the ball and socket connections for tight coupling and only switch to the use/depends line between component and provider for loose coupling where there component (interface realizations) can actually be switched, both are mixed in Scott Ambler's figure 1 (linked above), loose on the left and tight coupling on the right. The UML spec also mentions this in section 8 of the UML 2.2 Superstructure.
From the following topic in the VS 2010 Ultimate docs:
UML Component Diagrams: Guidelines: http://msdn.microsoft.com/en-us/library/dd409393%28VS.100%29.aspx
Drawing component diagrams has several benefits:
Thinking of your design with regard to the major blocks helps the development team to understand an
existing design and create a new one.
By thinking of your system as a collection of components with well-defined provided and required
interfaces, you improve the separation between the components. This in turn makes the design easier to
understand and easier to change when requirements change.
(source: microsoft.com)
Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 4 years ago.
Improve this question
I work a lot with decision makers looking to use technology better in their businesses. I have found that a picture is worth a thousand words and prototyping a system in a diagram of some sorts always lends a lot to a discussion. I have used Visio, UML (somewhat), Mind Maps, Flow Charts and Mocked Up WinForms to start the vision for these sponsors to ensure that everyone is on the same page. I always seem to be looking for that common process can be used to knit the business vision to the development process so that we all end up at the same end, "Something functional that solves a problem".
I am looking for suggestions or Cliff notes on how to approach the design process such that it works for applications that may only take a week to develop, but can also be used to encompass larger projects as well.
I know that this delves into the area of UML, but I have found that I have a hard time finding a guide to appropriately use the various diagram types, let alone help business users understand the diagrams and relate to them.
What do you use to capture a vision of a system/application to then present to the sponsors of a project? (all before you write a single line of code)...
Paper or whiteboard!
For the lone deveoper, I'd recommend paper. At least at first, eventually you may want to formalize it with UML, but I don't think its necessary.
For a group of developers that work together (physically), I'd recommend a whiteboard. That way its visible for everyone and everyone can improve and contribute. Again, you may want to formalize at this point, but I still don't think its neces
When I first started doing OOP (or designing an algorithm), I'd do it all in my head while coding. But after doing some reasonable complex projects I definitely see the benefit in drawing out the interactions between different objects in a system.
I do projects by myself, so I use lots of index cards for designing classes and paper for their interactions. The point is it needs to be easy to change. I've played with Dia, a diagram editor, for doing UML, but making changes is too difficult. I want to be able to be able to make quick changes, so I can figure out what works best.
Its worth mentioning that TDD and doing "spike"[1] projects can help when designing a system, too.
[1] From Extreme Programming Adventures in C#, page 8:
"Spike" is an Extreme Programming term
meaning "experiement." We use the word
because we think of a spike as a
quick, almost brute-force experiment
aimed at learning just one thing.
Think of drving a big nail through a
board.
For small or very bounded tasks, I think developers almost universally agree that any sort of diagram is an unnecessary step.
However when dealing with a larger, more complicated system, especially when two or more processes have to interact or complex business logic is needed, Process Activity Diagrams can be extremely useful. We use fairly pure agile methods in development and find these are almost the only type of diagrams we use. It is amazing how much you can optimize a high level design just by having all the big pieces in front of you an connecting them with flow lines. I can't stress enough how important it is to tailor the diagram to your problem, not the other way around, so while the link gives a good starting point, simply add what makes sense to represent your system/problem.
As for storage, whiteboard can be great for brainstorming and when the idea is still being refined, but I'd argue that electronic and a wiki is better once the idea is taking a fairly final shape (OmniGraffle is the king of diagramming if you are lucky enough to be able to use a Mac at work:) . Having an area where you dump all these diagrams can be extremely helpful for someone new to get a quick grasp on an overall piece of the system without having to dig through code. Also, because activity diagrams represent larger logic blocks, there is not the issue of always having to keep them up to date. When you make a large change to a system, then yes, but hopefully likely using the existing diagram to plan the change anyway.
Read up on Kruchten's 4+1 Views.
Here's a way you can proceed.
Collect use cases into a use case diagram. This will show actors and use cases. The diagram doesn't start with a lot of details.
Prioritize the use cases to focus on high value use cases.
Write narratives. If you want, you can draw Activity diagrams.
The above is completely non-technical. UML imposes a few rules on the shapes to be used, but other than that, you can depict things in end-user terminology.
You can do noun analysis, drawing Class diagrams to illustrate the entities and relationships. At first, these will be in user terminology. No geeky technical content.
You can expand the activity diagrams or add sequence diagrams to show the processing model. This will start with end-user, non-technical depictions of processing.
You can iterate through the class and activity diagrams to move from analysis to design. At some point, you will have moved out of analysis and into engineering mode. Users may not want to see all of these pictures.
You can draw component diagrams for the development view and deployment diagrams for the physical view. These will also iterate as your conception of the system expands and refines.
When designing an application (I mainly create web applications, but this does apply to others), I typically create user stories to determine exactly what the end user really needs. These form the typical "business requirements".
After the user stories are nailed down, I create flow charts to lay out the paths that people will take when using the app.
After that step (which sometimes gets an approval process) I create interface sketches (pen/pencil & graph paper), and begin the layout of the databases. This, and the next step are usually the most time consuming process.
The next step is taking the sketches and turn them into cleaned up wireframes. I use OmniGraffle for this step -- it's light years ahead of Visio.
After this, you may want to do typical UML diagrams, or other object layouts / functionality organization, but the business people aren't going to care so much about that kind of detail :)
When I'm putting together a design, I'm concerned with conveying the ideas cleanly and easily to the audience. That audience is made up of (typically) different folks with different backgrounds. What I don't want to do is get into "teaching mode" for a particular design model. If I have to spend considerable time telling my customer what the arrow with the solid head means and how it is different from the one that is hollow or what a square means versus a circle, I'm not making progress - at least not the progress I want to.
If it is reasonably informal, I'll sketch it out on a whiteboard or on some paper - block and simple arrows at most. The point of the rough design at this point is to make sure we're on the same page. It will vary by customer though.
If it is more formal, I might pull out a UML tool and put together some diagrams, but mostly my customers don't write software and are probably only marginally interesting in the innards. We keep it at the "bubble and line" level and might put together some bulleted lists where clarification is needed. My customer don't want to see class diagrams or anything like that, typically.
If we need to show some GUI interaction, I'll throw together some simple window prototypes in Visual Studio - it is quick and easy. I've found that the customer can relate to that pretty easily.
In a nutshell, I produce simple drawings (in some format) that can communicate the design to the interested parties and stake holders. I make sure I know what I want it to do and more importantly - what THEY NEED it to do, and talk to that. It typically doesn't get into the weeds because folks get lost there and I don't find it time well spent to diagram everything to the nth degree. Ultimately, if the customer and I (and all other parties concerned) are on the same page after talking through the design, I'm a happy guy.
I'm an Agile guy, so I tend to not put a lot of time into diagramming. There are certainly times when sketching something on a white board or a napkin will help ensure that you understand a particular problem or requirement, but nothing really beats getting working software in front of a customer so they can see how it works. If you are in a situation where your customers would accept frequent iterations and demos over up front design, I say go for it. It's even better if they are okay to get early feedback in the form of passing unit or integration tests (something like Fit works well here).
I generally dislike prototypes, because far too often the prototype becomes the final product. I had the misfortune of working on a project which was basically extending a commercial offering which turned out to be a "proof of concept" that got packaged and sold. The project was canceled after over 1000 defects were logged against the core application (not counting any enhancements or customizations we were currently working on).
I've tried using UML, and found that unless the person looking at the diagrams understands UML, they are of little help. Screen mock-ups are generally not a bad idea, but they only show the side of the application which directly effects the user, so you don't get much mileage for anything that isn't presentation. Oddly enough tools like the Workflow designer in Visual Studio produce pretty clear diagrams that are easy for non-developers to understand, so it makes a good tool for generating core application workflow, if your application is complex enough to benefit from it.
Still, of all the approaches I've used over the years, nothing beats a user getting their hands on something to let you know how well you understand the problem.
I suggest reading Joel's articles on "Painless Functional Specifications". Part 1 is titled "Why Bother?".
We use Mockup Screens at work ("Quick and Easy Screen Prototypes"). It's easy to alter screens and the scetches make clear that this is only a design.
The mockups are then included in a Word document containing the spec.
From Conceptual Blockbusting: A Guide To Better Ideas by James L. Adams:
Intellectual blocks result in an
inefficient choice of mental tactics
or a shortage of intellectual
ammunition. . . . 1. Solving the
problem using an incorrect language
(verbal, mathematical, visual) -- as
in trying to solve a problem
mathematically when it can more easily
be accomplished visually
(pg. 71, 3rd Edition)
Needless to say, if you choose to use diagrams to capture ideas that may be better captured with mathematics, it's equally bad. The trick, of course, is to find the right language to express both the problem and the solution too. And, of course, it may be appropriate to use more than one language to express both the problem and the solution.
My point is that you're assuming that diagrams are the best way to go. I'm not sure that I would be willing to make that assumption. You may get a better answer (and the customer may be happier with the result) via some other method of framing requirements and proposed designs.
By the way, Conceptual Blockbusting is highly recommended reading.
The UML advice works well if you're working on a large & risk-averse project with a lot of stakeholders, and with lots of contributors. Even on those projects, it really helps to develop a prototype to show to the decision makers. Usually walking them through the UI and a typical user story is quite sufficient. That said, you must beware that focus upon the UI for decision makers will tend to make them neglect some significant backend issues such as validations, business rules and data integrity. They will tend to write these issues off as "technical" issues rather than business decisions.
If, on the other hand, you're working on an Agile project where it's possible to make code changes quickly (and rollback mistakes quickly), you may be able to make an evolutionary prototype with all the works. Your application's architecture should be supple and flexible enough to support quick change (e.g. naked objects design pattern or Rails-style MVC). It helps to have a development culture that encourages experimentation, and acknowledges that BDUF is no predictor of working successful software.
4+1 views are good only for technical people. And only if they are interested enough. Remember those last dozen times you struggled to discuss use-case diagrams with the customer?
The only thing I found that works with everybody is in fact showing them screens of your application. You said yourself: a picture is worth a thousand words.
Curiously, there are two approaches that worked for me:
Present to users a complete user manual (before even development is started), OR
Use mockups that doesn't look at all like finished app: Discuss main screens of you app first. When satisfied, proceed discussing mockups but one scenario at a time.
For option (1) you can use whatever you want, it doesn't really matter.
For option (2) it's completely fine to start with pen and paper. But soon you are better off using a specialized mockup tool (as soon as you need to edit, maintain or organize your mockups)
I ended up writing my own mockup tool back in 2005, it became pretty popular: MockupScreens
And here is the most complete list of mockup tools I know of. Many of those are free: http://c2.com/cgi/wiki?GuiPrototypingTools