UML tool for team development

[Ilja Preuss]

Originally posted by Gerardo Tasistro:
Can I keep the whiteboard? Yes. But the printed copy from the software is so much more practical to work on at my desk. I do some prototyping, ground some ideas then rework the model. Write that down on the paper and then update the diagram. Sure I could update the whiteboard, but a pdf goes a lot faster through email than the whiteboard. So my team can have a view of my ideas before we sit down again at the whiteboard.

I think Scott hit the nail on the head - we are working in very different environments.

Section 11 (currently at the top) of http://xp123.com/xplor/room-gallery/ shows our team room. The whole team of six developers is sitting in this room, often pair programming. I can easily read the white board from the desk I'm sitting at. There simply is no need to email the diagram to other team members, or to have a copy at the desk - we can all see (and modify) it, anyway.

[Ilja Preuss]

Originally posted by Scott Ambler:

Ilja, I'd love to see your white board example written up in a bit more detail and posted on the web.

I will think about it. What kind of detail would you like to see?

[Gerardo Tasistro]

Oh I agree with Scott. We DO have different environmnets. But that has little to do with the matter at hand. Which is UML software tool usage and the original question.

I'm looking forward to Scott's answer on the matter of no-cost UML tools. The "there is no vendor breathing down your back" scenario.

I also believe that while a piece of paper is useful for getting a price quote on a project nobody really sends that scribble to the client as a quote. Why don't we apply the same "neatness" standard to diagrams and documentation? And if you can get Open Office and type up your memos and price quotes, why not get Argo UML and sketch your UML?

[Ilja Preuss]

Originally posted by Gerardo Tasistro:
Stan I believe Ilja is missing the fact that I'm moving beyond the meeting.

I wonder why you believe this.

Sooner or later the UML on the whiteboard will be pretty much terminal.

Yes. That's when it isn't needed any longer...

Why not keep a copy of it in a digital format that isn't a JPEG. It is good reference, looks nice, can be transfered around and doesn't cost much (using open source products).

I don't feel the need to transfer it around. And I don't need it to look nice.

In fact the longer I think about it, I feel that I *don't want it* to look nice. I want it to look inviting to collaborate. I want it to say "I'm an organic thing, please change me as you see fit", not "someone put a lot of effort into me to get me nice, don't mess me up."

Regarding being a "good reference", I don't think so. Remember, it is a simplified, abstract view on the actual system, *specifically* created for the task at hand. A diagram for a different task very likely had to look quite differently - focus on parts not shown in this diagram, and ignore some others that are important to the current task.

Additionally, we do a lot of "merciless refactoring" - the design really changes continuously. The diagram would fastly become outdated, or a burden to keep up to date.

[Ilja Preuss]

Originally posted by Stan James:
(From which I infer (big leap) that Ilja doesn't have formal design reviews, and I'm all the more sad that we do.)

You are right, we don't have those.

BTW: Ilja, does your picture say "Chili con carne" near the lower left? Now I have to go out for Mexican.

Yes, it does. Every Thursday, two of us are cooking for the rest of the team. Chili con carne is one of my specialties...

[Gerardo Tasistro]

Well I think the diagram is a great thing to keep around for future reference. You never know when you need to do maintenance on a thing and IMHO maintenance usually takes a lot more effort to get going than a ground up development. So anything that helps you get up to speed on how something was implemented is a great plus.

"organic" and "sloppy" are not synonyms. They're not binding and are not mutually exclusive either. I also find it really quick to do a diagram on software. Didn't take me more than two minutes to get your diagram down on the PC.

Finally, the "merciless refactoring" is the reason I moved from the free UML tools to the comercial. I wanted to "see" the refactoring in the UML without having to redo the diagram by hand. Just point the tool at the source code and have it render the UML in seconds.

[Don Morgan]

I pointed out that my bill rate was fairly high and that I felt it would be unprofessional to spend several days creating slick looking diagrams when I could spend several minutes cleaning up the snapshots which conveyed the exact same information. The C-level people in the room agreed with me.

Although I see this is the situation you were in, it is odd to compare the length of time to EDIT existing snapshots of hand drawn diagrams with the length of time to CREATE the diagrams using a tool. This would raise the question as to why the diagrams were not in a tool to start with so they could also be edited in a few minutes. (Almost) anything is possible, but I can not imagine any change which would take minutes to edit in a hand drawn diagram, yet days to edit in a tool, there is simply not a two orders of magnitude difference between the two for similar tasks (the real apples to apples comparison).

Also, often for high level management, the diagrams are much simpler, in which case I sometimes find it useful to do them on the fly, on a whiteboard, in the presentation room. Doing it on the fly has the advantage that your audience's attention is naturally attracted to the portion you are drawing (and explaining!), as opposed to showing the complete diagram at once, in which case your audience may be looking at a different portion than the portion you are talking about. Of course, there are ways around this with pre-drawn diagrams (such as only showing a small portion at once and covering the rest).

The important part, the real creative process, is to come up with the design in the first place and then correctly grow and evolve it. This I actually find easier to do on paper or a whiteboard, since I find using a pen and paper or whiteboard encourages thinking more than a mouse and keyboard, but then transferring the design into a tool is mechanical, and quick and easy to do.

Of course, tools are not "deposit" only. Often we would print out diagrams, spend hours editing the diagrams with a pencil or pen (the real design or thinking process), then spending a few minutes to put the changes back into the tool (the "mechanical" part).

Even when coding, I find it beneficial to write out on paper and think through at least the overall program structure and flow before hitting the keyboard, but this is just my own preference. This is NOT a big up-front effort, but just something short term, to get you started and that you may refer to and modify as your learn more while writing the code. This may be quickly discarded (or, more likely, a number of them will pile up on your desk!).

People often confuse "designing" with "documenting the design". Choose the tool which helps you the most for each of them. Of course, how you present or communicate the design to an audience is then another different issue.

[Ilja Preuss]

Originally posted by Gerardo Tasistro:
Why don't we apply the same "neatness" standard to diagrams and documentation?

What advantage would that give us?

[Ilja Preuss]

Originally posted by Gerardo Tasistro:
Well I think the diagram is a great thing to keep around for future reference. You never know when you need to do maintenance on a thing and IMHO maintenance usually takes a lot more effort to get going than a ground up development.

The diagram shown is for a feature that is to be incorporated into a part of a system that is now in use and under continuous development for over 8 years. It consists of over a million lines of code in near to hundred interdependent CVS modules. What we are doing *is* maintenance.

"organic" and "sloppy" are not synonyms.

I don't think of the white board diagram as "sloppy".

Finally, the "merciless refactoring" is the reason I moved from the free UML tools to the comercial. I wanted to "see" the refactoring in the UML without having to redo the diagram by hand. Just point the tool at the source code and have it render the UML in seconds.

I seriously doubt that for our case any tool could generate a meaningful diagram from the existing code without serious human intervention. It really is a heavy simplifaction over what the code really looks like.

[Gerardo Tasistro]

Originally posted by Ilja Preuss:


What advantage would that give us?

Well guess if you have to ask then no answer will suffice.

[Stan James]

I'd guess Ilja tried it, found no value, and just stopped doing it. That's a good thing because making them isn't free. That's a very common theme among the agile crowd; see AgileModeling.com for much more.

Of course that doesn't mean archived diagrams won't have value to you. I have to produce a certain number of really nice documents for people who care about such stuff. The only value these have is making somebody else happy. They are usually colorful 3D PowerPoint boxes and arrows; I see almost no real UML at work.

I do keep a few diagrams around because of dark corners of the system that are too complex to keep in my head. If I had the ability to tear apart some of the vendor framework those corners would be better lit by now and the code would tell me what I need to know.
[ January 31, 2006: Message edited by: Stan James ]

[Scott Ambler]

I will think about it. What kind of detail would you like to see?

Earlier in the thread you had an example picture and a brief write up. That would be a great start. My suggestion would be to flesh out the description a bit, perhaps with some of the points you've been making throughout this discussion.

- Scott

[Scott Ambler]

Can I keep the whiteboard? Yes. But the printed copy from the software is so much more practical to work on at my desk. I do some prototyping, ground some ideas then rework the model. Write that down on the paper and then update the diagram. Sure I could update the whiteboard, but a pdf goes a lot faster through email than the whiteboard. So my team can have a view of my ideas before we sit down again at the whiteboard.

That's one way to work, but it's not very agile. On agile teams we work together, we know that working alone isn't very effective because it injects defects and puts us at risk that the person working alone will go off in a questionable direction for awhile and thereby waste time. On an agile team if there is value in updating a model then we do it together. If that's at a whiteboard, or on paper, or at a screen then that's fine, but we don't work alone.

Although in another post you indicated that the differences in environments aren't important, the reality is that the differences are incredibly important. You haven't had a chance to work in the manner which Ilja and I are describing, so it's difficult to envision these differences. When you're working together collaboratively, instead of handing off information to people, you discover that you can do a lot less work.

Now I'd like to ask you Scott. What's your gripe with CASE tool vendors? And all you know about are comercial apps? Before I went out and spent a thousand bucks on Poseidon I used Argo UML and UMbrello for years. Tools which are both free. And I had no vendor breathing down my back. I moved on to Poseidon when I had needs Argo or UMbrello couldn't satisfy. None of which are related whiteboards.

Bottom line is you don't have to spend a buck on software to have UML software tools. They add quite a few features whiteboards don't have. They don't substitute whiteboards for brainstorming, but they beat it in neatness, editing(move, copy, paste) and replicability. And just like it happened with office productivity tools, these too will become comodity items over time. So more features will get added with no added cost.

I've worked with these low cost tools too, because sometimes my clients aren't willing to invest in the commercial tools.

Actually, the bottom line isn't the price of the tool. From a financial point of view, the real issue is total cost of ownership (TCO). You could spend $10,000 on a CASE tool and that would still be only a fraction of the TCO. This is basic management accounting.

One of the principles of Agile Modeling is Maximize Stakeholder Investment, you want to spend the money wisely. One way that you do that is be reducing the TCO of the tools that you use, motivating the AM practice Use the Simplest Tools. Sometimes the simplest tool is a CASE tool, very often it isn't.

- Scott

[Scott Ambler]

Although I see this is the situation you were in, it is odd to compare the length of time to EDIT existing snapshots of hand drawn diagrams with the length of time to CREATE the diagrams using a tool. This would raise the question as to why the diagrams were not in a tool to start with so they could also be edited in a few minutes. (Almost) anything is possible, but I can not imagine any change which would take minutes to edit in a hand drawn diagram, yet days to edit in a tool, there is simply not a two orders of magnitude difference between the two for similar tasks (the real apples to apples comparison).

Actually, it does. In this situation we had been working in a large room covered in whiteboards. I literally went around the room with a camera, took about 30 snapshots (kept only 10), cleaned them up with WhiteboardPhoto (about a minute a pic), and then dropped them into Powerpoint (and into CVS, not that we ever went back to them). Transcribing those 10 diagrams into something like Visio would have taken a couple of days.

The important part, the real creative process, is to come up with the design in the first place and then correctly grow and evolve it. This I actually find easier to do on paper or a whiteboard, since I find using a pen and paper or whiteboard encourages thinking more than a mouse and keyboard, but then transferring the design into a tool is mechanical, and quick and easy to do.

Yes, the vast majority of modeling is done using simple tools, not CASE tools even when they're available. At UML World last year I attended a panel session discussing the future of modeling. Every panelist worked for a vendor, and in their initial position statements they all discussed the imporatance and benefits of CASE tools. I was the first one to ask a question, and my question was "Without plugging the tools of your company or tools of companies that you worked for in the past, what is the most effective modeling tool you've ever worked with in your career?" Every single one of them said whiteboard, yet not one had mentioned the work up until that point in their discussion of the future of modeling.

Everyone that I know of works with simple modeling tools, and sometimes with CASE tools (yes, I use them too), but it's pretty rare to see coherent discussions of this being done in practice. How many modeling books do you know of that contain sketches in them for example? It's something that we all do, including the authors, yet rarely gets written about.

- Scott

[Gerardo Tasistro]

Scott I never said one works alone. But eventually you have to turn your back to the whiteboard and face the screen. At that point I find it useful to have a paper copy of the whiteboard. I don't know, maybe I'm old. I just find it a lot less painful for my neck to move my eyes over to the piece of paper than to the whiteboard. Leaving arthritis behind I also find it useful to scribble on a piece of paper ideas as I work, notes and commentaries. Also make modifications and "batch" them on the paper before modding the whiteboard(like you say).

Now the issue here is what sort of printed copy do I have. Do I have a photo of the whiteboard or a software UML printed diagram. It can be argued that taking a photo is quicker. But I've found out it is a marginal benefit that quickly erodes. Not everybody in the team has a camera so taking a shot and then emailing the diagram to others to print takes at best half the time to capture the diagram on software and ship an 8k pdf. So the capturing the diagram takes longer line (after all the brainstorming has gone down on the whiteboard) doesn't fly too high with me.

Now with a piece of paper we can mature the diagram until the whiteboard is free. You erase the whiteboard and keep the diagrams. Which can be argued that they're not important, that we can see the code and understand the program. I don't buy that either. I think that all those pieces of paper help you later on. They also help new team members who were not in the beginning.

Now another problem with whiteboards is that I never seem to have enought of them. If we work on the view part we have to draw prototypes of the views, pages and navigation. Then we get to the data structure or the inner logic of things or maybe the user schema(who has rights to what).

In my experience whiteboards at this stage have become a burden. If I use Ilja's schema I can't erase it because I don't have a hardcopy. But along the lines of the prototyping to the client we find new things in the views and navigation. Can't do much because we have another diagram "on screen".

That is why I've found UML software tools to be extremely helpful. Over time whiteboards reach their limits. When you have to sit down with your team members and check parts of the system they're working on whiteboards don't sufice. UML starts to stack on paper and now I work the details on the whiteboard. I find it impossible to have the whole project on the board and without printed copies we'd be lost. So to sum it up:
- brainstorm and startup on whiteboard
- diagram on software
- whiteboard is free for other diagrams
- work a bit, suggest modifications
- in a meeting those are worked on paper and whiteboard (mods and ideas on whiteboard)
- software diagram is update to reflect changes, those changes are hardcopied for everyone to have and remember what was agreed upon
- whiteboard is free for other diagrams
- cycle repeats

I hope I'm making myself clear. I agree with you both that whiteboards are the way to go in meetings. That they acelerate brainstorming and startup. But beyond that. After you move beyond the "node" or "component" level you can't keep up with the project just on the whiteboard. I haven't found a way to put it all on a whiteboard that will fit and I have found that a hardcopy is great for reference.

I'd like to have your and Ilja's feedback on how you work on different components of a project. Or maybe different projects at the same time. How do you do this? For example how do you have the front end and back end of a site on the whiteboard? And how do you remember what components go were without a printed copy. And granted some tools are free and fully functional do you really believe a hand scribbled diagram is good enough vs say a "neat" printed copy from an UML software? Because you see I can argue that having Christmas dinner on three plastic tables with a plastic cover is trully functional. That the plastic tables can be stored away while a wooden table takes space in the dinning area all year round (adding to the TCO of having dinning space built into your house while reducing costs of purchase vs say a wood table). The plastic cover lasts forever practically and is easier to clean than a cloth cover (further reducing TCO). And if I don't invite the neighbors nobody would notice. But hey doesn't it feel great to have dinner on a nice solid wood table with all your family around!

Do you guys really think you don't deserve a good clear printed diagram of your whiteboards? Given that there are free tools for it.

[Gerardo Tasistro]

Originally posted by Scott Ambler:

Every panelist worked for a vendor, and in their initial position statements they all discussed the imporatance and benefits of CASE tools. I was the first one to ask a question, and my question was "Without plugging the tools of your company or tools of companies that you worked for in the past, what is the most effective modeling tool you've ever worked with in your career?" Every single one of them said whiteboard, yet not one had mentioned the work up until that point in their discussion of the future of modeling.

- Scott

Well I wasn't expecting them to point their finger at the next booth. Did you? What did you expect them to say?

"Oh I worked with Rational, but now that I'm with "3Sj303j22-whatever" I have to deal with these limitations. And well..."

or maybe

"Oh I just sell them. I don't work with them"

IMHO they wouldn't be too good a salesperson if they said any of these lines.

But the of course we also have to analyze your question a bit further.

"Without plugging the tools of your company or tools of companies that you worked for in the past, what is the most effective modeling tool you've ever worked with in your career?"

Lets see. Strictly speaking your question excludes all tools. Since it not only excludes the tool from the current company, but all previous tools too. Since you say "that you worked for in the past".

Given CASE tools are very recent development I find your question to be similar to asking good ol Gutemberg, "Excuse me Johannes. Excluding your machine... what has been the most effective tool to copy books that you've ever worked with in your carrer?"

Should we go back to hand copy of books?

[Ilja Preuss]

Originally posted by Gerardo Tasistro:

Well guess if you have to ask then no answer will suffice.

I'm confused.

I understand that the tool-generated UML diagrams have some value to you. I tried to explain why I don't see that the advantages you mentioned would be valuable to our team. Still you seem to insist that it would be a good idea to do for us, too.

So are you saying that

- if something is cheap and nice, there doesn't need to be an additional advantage to be motivated to do it,

- you don't believe me that the advantages you mentioned wouldn't be of value to my team,

- you see some value that we didn't yet discuss, or that I didn't "refute", or

- something different?

[Scott Ambler]

Lets see. Strictly speaking your question excludes all tools. Since it not only excludes the tool from the current company, but all previous tools too. Since you say "that you worked for in the past".

Given CASE tools are very recent development I find your question to be similar to asking good ol Gutemberg, "Excuse me Johannes. Excluding your machine... what has been the most effective tool to copy books that you've ever worked with in your carrer?"

I doubt very highly that each panelist worked for every single tool vendor. And, several of the panelists had in fact mentioned the tools of other vendors.

Furthermore, CASE tools have been with us since the mid-1980s.

- Scott

[Ilja Preuss]

Originally posted by Stan James:
I'd guess Ilja tried it, found no value, and just stopped doing it.

In fact, every couple of years I try again, just to be sure...

Nearly a decade ago, I produced some UML using a software tool for a feature I just implemented before leaving the team. That team was much less collaborative than the current one, though. And of course I have no idea whether the diagram proved to be valuable to those who came after me, although I hope that it did.

Two years ago, a coworker and me took two days to create a UML diagram of a complex part of the code that we needed to work on. We printed it on several pages and pinned it to the wall. It hang there for several months, but wasn't used once. We both agree that producing the diagram was invaluable, but the printed out diagram was useless.

[Gerardo Tasistro]

Originally posted by Scott Ambler:


I doubt very highly that each panelist worked for every single tool vendor. And, several of the panelists had in fact mentioned the tools of other vendors.

Furthermore, CASE tools have been with us since the mid-1980s.

- Scott

I never said each panelist worked for every single tool vendor. I did say that every single tool vendor THEY EVER WORKED FOR got excluded by your question. I think you had your arrows pointing the wrong direction when you read my paragraph.

The printing press has been around much longer and before that written language had been around much much longer. So I guess your comment on CASE tools being around since the mid 80's backs my point.

[Ilja Preuss]

Originally posted by Gerardo Tasistro:
Scott I never said one works alone.

With all due respect, not working alone is not the same as a highly collaborative workplace. For example, how much experience do you have with Pair Programming?

But eventually you have to turn your back to the whiteboard and face the screen.

Yes. For us, tight collaboration doesn't end at this point.

At that point I find it useful to have a paper copy of the whiteboard. I don't know, maybe I'm old. I just find it a lot less painful for my neck to move my eyes over to the piece of paper than to the whiteboard.

Well, yes, perhaps I'll say the same in twenty years...

Leaving arthritis behind I also find it useful to scribble on a piece of paper ideas as I work, notes and commentaries. Also make modifications and "batch" them on the paper before modding the whiteboard(like you say).

Some of this probably gets replaced by discussions with the pairing partner. Of course this doesn't mean that we don't scribble something on paper from time to time. I don't remember feeling the need to have a copy of the white board for this, though - often simply reproducing part of the diagram on the fly works just well.

Not everybody in the team has a camera so taking a shot and then emailing the diagram to others to print takes at best half the time to capture the diagram on software and ship an 8k pdf.

Frankly, I don't have much experience with photos - we don't even need those very often.

But nevertheless I don't think that argument holds for the general case. With six developers in one room, it would be hard to imagine to need more than one camera, or not being able to simply print a photo for your coworkers. For a highly collocated and collaborative team, I don't see where the need to email the photo would come from.

Which can be argued that they're not important, that we can see the code and understand the program. I don't buy that either. I think that all those pieces of paper help you later on. They also help new team members who were not in the beginning.

Our new team members are introduced to the design by pair programming - which, of course, includes sketching a diagram now and then.

A lot of the design actually is in the heads of the developers - where, after all, it needs to be. And I actually don't find it too hard to understand the design from well-designed code using a powerful IDE (like Eclipse).

So to sum it up:
- brainstorm and startup on whiteboard
- diagram on software
- whiteboard is free for other diagrams
- work a bit, suggest modifications
- in a meeting those are worked on paper and whiteboard (mods and ideas on whiteboard)
- software diagram is update to reflect changes, those changes are hardcopied for everyone to have and remember what was agreed upon
- whiteboard is free for other diagrams
- cycle repeats

Our workflow is very different. Most of what probably happens in your meetings is done by us through promiscuous pair programming, with some spontaneous white board discussions.

For example how do you have the front end and back end of a site on the whiteboard?

I'm not sure I understand that question. Do you have an example?

And how do you remember what components go were without a printed copy.

We don't need to, as the discussion goes on during implementation. In fact, most of it is actually decided during implementation.

And granted some tools are free and fully functional do you really believe a hand scribbled diagram is good enough vs say a "neat" printed copy from an UML software?

Well, why wouldn't it? What makes a "neat" diagram better than a hand scribbled one - other than that it might look more pleasing to the eye (which probably is a matter of taste)?

But hey doesn't it feel great to have dinner on a nice solid wood table with all your family around!

Well, yes, of course! That's why we have lots of plants in our team room, for example - they make us feel good. We even had a christmas tree again last year, including fairy lights indicating the current state of our build server - totally needless, but cool!

Do you guys really think you don't deserve a good clear printed diagram of your whiteboards?

I don't feel bad about scribbled diagrams on the white board at all. In fact, I really like them. They give me a much more warm feeling than any "clear printed" copy could ever do.

Perhaps that's really the gist of our disagreement?

[Gerardo Tasistro]

Originally posted by Ilja Preuss:


I'm confused.

Yes we agree on that.

Originally posted by Ilja Preuss:

I understand that the tool-generated UML diagrams have some value to you. I tried to explain why I don't see that the advantages you mentioned would be valuable to our team.

It is clear to me you don't see the value of them to your team. I'm posting here to clarify these values not to impose them on you.

Originally posted by Ilja Preuss:


Still you seem to insist that it would be a good idea to do for us, too.

I couldn't care less about what you or your team use. I'm posting here to show the benefits of software UML tools. And to add a response to the original poster who did ask for a software tool and did require documentation and archives of the project. Especifically to answer a need of a team UML tool.

If we read back...

Originally posted by Leandro Oliveira:

But we have to archive the project.

Originally posted by Ilja Preuss:

What for?

You could use electronic whiteboards, or http://www.polyvision.com/products/wbp.asp

Well there Ilja, speaking of the devil. It is clear that Leandro needs the tools with those features. And you answer "What for?" Now since you don't have the need you find no other person should have the need too.

Originally posted by Ilja Preuss:

- if something is cheap and nice, there doesn't need to be an additional advantage to be motivated to do it,

This goes along Scott's apparent vendetta against any and all software UML and the implied "vendor breathing down your back".

Do you remember

Originally posted by Scott Ambler :


So why does the MDA get so much press but whiteboard modeling virtually nothing? Because the tool vendors don't make any money sell whiteboard markers, the consultants can find more business helping you with a complex approach (e.g. MDA) instead of a simple one, and the computer science academics rarely do observational studies so they don't have a clue as to what is happening in the real world.

To this I replied the set of free UML tools available. Indicating that while press can be created by the vendors, you can get UML for free from other third parties. That the vendors are promoting CASE tools, but at the same time UML and diagraming. Which is in esence what you do on a whiteboard. So Ilja. Do you do diagrams on whiteboards because you need them or because some vendor is pushing it and you can't aford his tools? I believe that you do it because you need them. Clearly you don't need the tools nor do you need archives of your project or documentation. But Leandro does and he made it very clear. Yet over and over again in this thread you've said documentation and neatness and printed copies and archived whiteboards are not needed. When in truth it is you and your team that doesn't need them. So who's pushing what on who?

Originally posted by Ilja Preuss:

- you see some value that we didn't yet discuss, or that I didn't "refute", or

- something different?

Refute? Now now a nice question is why use that word? So you're here to "refute". Talk about imposing one's views on others. If in doubt go back to the "What for?" section of this post.

[Gerardo Tasistro]

My experience with "paired programming" would be better termed as "paired development". My major is electronics engineering and initially I worked in "paired" form around hardware design and programming. In which you need to be in tight group with your programmer.

It is from there that I got used to using software tools for development and documentation. Try making a circuit board without a tool like Protel and you'll be working a lot. You can put the ucontroller on the whiteboard. Do some filter stuff, PLL etc. And it will all be quick and nice until the point were you have to build a circuit board or simulate the circuit.

So maybe I have a lot of experience working like this and I just need it. Not to mention documentation. Since most embedded stuff is done at assembler or C at very low levels you have to hand over documentation of what pin does what on the ucontroller. And the clearer the better. For your programmer and for the tech guys later.

Now I work on online stuff and software connected to specialized hardware. So I still require the documentation to work with HW. And I still have the craving if you will for formal software documentation.

To answer your question on the front end vs back end.

I have to control various types of hardware to get readouts. Now you wouln't believe what some of these guys come up for protocols over the line. So we might have a meeting about one box and its protocol. Do a diagram and understand it. But sometimes that diagram fills the whiteboard. Should I stop working until I can erase the whiteboard? Nope, just UML it on paper and keep working on the next part.

Ok how does this fit into the big picture. A plugable protocol handler. So this package that handles comm with box B type has to be introduced to the bigger program. Ok were is the documentation? What is the program expecting? Ok here is the UML for that system. Our protocol handler fits in right here. Ok we are done here.

Now the user has to be able to know what type of box? Yes or no. Lets say yes. So the configuration screen has to show this. How was the web interface built? We did it 2 years ago. Mhhh here are the docs. Ok so maybe just move this around. Refactor here. This class gets changed to this. Put a little select box here on the view. Bla bla bla.

Now if my whiteboard has the the comm protocol on it how do I fit the last paragraph in? More so. Do I rewrite the snapshot we took of the web interface whiteboard diagram from two years ago to add the new stuff and the take another snapshot? Or do I open up the UML and print it? Talk it over with my team (maybe on the whiteboard) then take note on the paper and modify the UML on software.

[Ilja Preuss]

Originally posted by Gerardo Tasistro:
I'm confused.
--------------------------------------------------------------------------------



Yes we agree on that.

Gerardo, when I first read this, I assumed that there simply was a smiley missing. But after reading the whole post, it feels more like your post is again lacking of respect. I don't feel comfortable about this.

It is clear to me you don't see the value of them to your team. I'm posting here to clarify these values not to impose them on you.

OK.

Still, I have a question: can you imagine that four my team, it really *wouldn't* have the value your team gets from it?

I couldn't care less about what you or your team use.

Mhh, well, it seemed to me that you were at least somewhat surprised by the fact that we don't see value in it, even resisted to believe that it really wouldn't have value. Could just by my perception, though...

And to add a response to the original poster who did ask for a software tool and did require documentation and archives of the project. Especifically to answer a need of a team UML tool.

You keep insisting on taking the question literally, I keep on taking it more broadly. I don't see why your interpretation should be the only valid one. Remember, I have no problem with your suggestion of a software tool, just with you implying that any mentioning of the possibility to use a non-software tool is off topic.

Well there Ilja, speaking of the devil. It is clear that Leandro needs the tools with those features. And you answer "What for?" Now since you don't have the need you find no other person should have the need too.

"What for?" was a serious question. I wanted to know what he needed to archive the diagrams for. If I had wanted to say that he doesn't need to archive the diagrams, I would have said so directly.

Originally posted by Ilja Preuss:

- if something is cheap and nice, there doesn't need to be an additional advantage to be motivated to do it,

Just for the record, that was a question where I asked whether that is what *you* wanted to say. It doesn't look like your follow up in any way answers that question, so I'm not sure why you quoted it.

Clearly you don't need the tools nor do you need archives of your project or documentation. But Leandro does and he made it very clear.

Not very clear to me, which is why I asked for details.

Yet over and over again in this thread you've said documentation and neatness and printed copies and archived whiteboards are not needed.

Now I'm really puzzled - how did you come to that impression? I just skimmed over my previous posts, and as far as I can tell, they are littered with "in my experience", "not to me" etc. pp. Hell, I even suggested a software tool to archive whiteboard UML...

And I'm *seriously* still interested in learning what value "neatness" has for you - I'm *really* at a loss regarding this.

So who's pushing what on who?

No intention on my side to push anything on anyone, just to share my experience and to learn from others.

Originally posted by Ilja Preuss:

- you see some value that we didn't yet discuss, or that I didn't "refute", or
--------------------------------------------------------------------------------

Refute? Now now a nice question is why use that word?

Well, I notice that this was a rhetorical question, but I will answer it anyhow:

I used "refute" because my online dictionary didn't come up with a better word.I put it into quotes because I felt that it might not be fully appropriate, to indicate that it should be taken with a grain of salt. I regret that I didn't take the time to find a better word.

What I meant was that I explained why I don't see the value for our team.

[Gerardo Tasistro]

I think then we have reached the end of this. If you feel ofended by the "confused" comment when it is clear you were confused in regards to something I said.

I'm clear on the fact that your team doesn't get the value I get from UML tools. Yet those values are still there even if not aplicable to your team. In other words. Should you happen to take on the use of UML with your team. That would not have an effect on the values of these tools on me or my team. Those values are there for me regardless of your usage or lack of usage.

BTW, I get the impression you have low regard for documentation from the following lines along various posts.

And keeping track of history is important because...? And a history of white board photos would fullfil that need because...?
-------
What would be unprofessional about such a documentation? Why should I, as a developer who has to work with such a documentation, care? With other words, what bad would happen because of the existance of such a documentation?
-------
I expect this diagram to be updated during the next days while we work on the feature, and to simply be discarded once we are finished with it.
-------
Regarding being a "good reference", I don't think so. Remember, it is a simplified, abstract view on the actual system, *specifically* created for the task at hand. A diagram for a different task very likely had to look quite differently - focus on parts not shown in this diagram, and ignore some others that are important to the current task.

Additionally, we do a lot of "merciless refactoring" - the design really changes continuously. The diagram would fastly become outdated, or a burden to keep up to date.

It is clear that you have little value for diagrams beyond the short term software development. And this whole confusion comes from those conflicting views. I understand your position and I also understand your questioning of Leandro's need for archives.

But please understand this:

Although Leandro's need for documentation could be questionable. And thus your "what for?" question would be valid. Once it is settled that is is or under the hypothetical situation in which it is. Then it is. And no amount of arguments can make that go away. He needs documentation and now the question at hand is which tool is best.

Should it be photographed whiteboards? Well could be, but you can't speak too much about that. Because you don't use them. I probably have more experience with that than you.

Frankly, I don't have much experience with photos - we don't even need those very often.

Should it be a software UML tool? Well maybe. According to me it should. But then again I could be wrong. But can you question me on that? Not really because it seems you have very little experience with documentation. It is also clear you have very low regards for it and its neatness. Above that you barely use software UML tools.

So Ilja what is your point here? What do you want to get to? That Leandro doesn't need to document and archive stuff? Who are we to tell him that?

Do you recommend that he just do diagrams on whiteboards and archive photos? Is that what you want to get to? Interesting when you don't even do it yourself.

What exactly is your point and how does it benfit Leandro?

Now I'm confused and I'm sure you'll agree on that to. Worry not. I will not be offended or find it a lack of respect.

[Mark Spritzler]

Some people like to be more detailed and want that software, some like whiteboard. Both views are accurate and right. So what makes the difference, pros and cons and your own likes.

Personally I like being detailed and write that big sequence diagram. But I also know that I do not need to keep it up to date. I do it to get my detail design and ideas out on paper, so that when I get to coding I am basically just typing, and when I find bad judgments, (which I have many), then I refactor and don't need to update the diagram because it has already serverd my purpose of what I want to use if for.

But that doesn't mean it is the only way to do it and that all other ways are wrong.

Mark

[Ernest Friedman-Hill]

Originally posted by Gerardo Tasistro:
That Leandro doesn't need to document and archive stuff? Who are we to tell him that?

Many of us are proponents of agile development methods. One of the principles of agile development is that before you do something, you should make sure that it's worth doing. Any many people who have been through that process have concluded that formal documentation -- and especially the effort of keeping it in sync with software as that software is developed -- is far more trouble than it's worth. There are other, more efficient ways to bring new developers up to speed: pair programming is one.

Anyway, that's who we are: people who would like to save Leandro some needless work, if possible.

If someone comes to you and says "I need to dig a hole, do you have a bigger spoon than this?" would you, or would you not tell him about shovels?

[Gerardo Tasistro]

Originally posted by Ernest Friedman-Hill:

One of the principles of agile development is that before you do something, you should make sure that it's worth doing. Any many people who have been through that process have concluded that formal documentation -- and especially the effort of keeping it in sync with software as that software is developed -- is far more trouble than it's worth.

Ernest I understand this. And I've persistently stated that I do use whiteboards as the idea gets cooked. But once it is settled and I know it is worth doing. I document it with a software tool.

Does agile development banish, forbid and abhore formal documentation. Or is it something it promotes as just dispensable.

[Ernest Friedman-Hill]

Originally posted by Gerardo Tasistro:

Does agile development banish, forbid and abhore formal documentation. Or is it something it promotes as just dispensable.

No, it's not forbidden; but you have to need it, which is different from wanting it or feeling like you need it. If a team finds that formal design documentation is worth the effort of keeping it up -- in other words, the project would be harder and take longer without the documentation -- then there's no problem with doing it at all.

I can't speak for anyone else in this thread, but I personally haven't seen a project yet where formal design docs were really worth the effort. In fact, I've seen more projects where they had negative value: generally because they were perpetually out of date, and so work was lost due to misleading documents.

So it's my personal opinion -- and I'm not alone in this -- that many more people think they need formal design docs than actually need them. The OP actually says he's "new at design", so this seemed like a good point at which to educate him. That's just what I do.

[Gerardo Tasistro]

Well I guess here we have to see also what or how "deep" formal documentation needs to be. Do we document every single call, program flow, etc? I personally don't think it is needed. What I've found over time good enough for me are:

- data structure models (class diagrams) automatically made from the code
- block diagrams of nodes and components to get a feel of what is in the application
- some flows or comunication diagrams for particularly tricky parts of processes or for critical processes
- use case diagrams to know who you have to look talk to (humans) and as "training-teaching-explanation" sessions

That aside I don't need any "deeper" docks like full package-class diagrams or every single comunication or call between classes documented.

EDIT>>>>

I just got a chance to read some chapters of A Practical Guide to Enterprise Architecture (co authored by Scott)

Here are a few points from it (hope Scott doesn't mind)

#

It maximizes stakeholder investment. The benefit provided by an agile document is greater than the investment in its creation and maintenance. Ideally, the investment made in that documentation was the best option available for those resources. In other words, no better approach was available to you.
#

It is "lean and mean.". An agile document contains just enough information to fulfill its purpose. It is as simple as it can possibly be.
#

It describes "good things to know.". Agile documents capture critical information that is not readily obvious, such as design rationale, requirements, usage procedures, and operational procedures.
#

It has a specific customer and facilitates the work efforts of that customer. You must work closely with customers, or potential customers, for your documentation if you want to create something that will actually meet their needs.
#

It is sufficiently accurate, consistent, and detailed. Agile documents do not need to be perfect; they just need to be good enough.

Given these points(very valid IMHO). It is important to quantify how much is too much and how much is too little. After that things fall into place and decisions can be taken.

Do we need this diagram showing how we parse a string? vs Do we need this diagram showing how we comunicate with the bank's VPOS?

Do we need a diagram of this bean with three properties? vs Do we need the diagram of this data structure that contains user data, configuration information, records of events and will all be stored as XML?

I think a great deal of this discussion has been going on as I look at the later examples while others look at the former and conclude they don't deserve a diagram. I wouldn't diagram it either.
[ February 01, 2006: Message edited by: Gerardo Tasistro ]

[Ilja Preuss]

Originally posted by Ernest Friedman-Hill:
No, it's not forbidden; but you have to need it, which is different from wanting it or feeling like you need it.

More specifically, a principle from the Agile Manifesto applies here:

The most efficient and effective method of
conveying information to and within a development
team is face-to-face conversation.

Of course this doesn't mean that we totally disregard written communication - just that we have a much stronger bias to more "hot" communication channels than we typically find in "conventional" teams.

[Scott Ambler]

Agilists document, it's just that we focus on high-value documentation. We put a price tag on documentation, and ask our stakeholders to prioritize the development of it. Yes, we treat it like any other requirement. It's the stakeholder's money, they should decide how it's spent, not us.

See Agile Documentation for some ideas. Also, you might find Communication on Agile Software Projects interesting.

- Scott

[Mark Spritzler]

The most efficient and effective method of
conveying information to and within a development
team is face-to-face conversation.

That is what scares me about Agile, is that it is extreme. Sometimes you can't get that face-to-face and it bogs down the process and makes it take longer to get things done. It is not efficient in that case. Now, I know they meant the statement in more general terms, but other, those that implement Agile, tend to take it to the extreme and declare no more written communication. So the Face to Face information sometimes gets lost and difficult to recreate if the two sides leave the company and months down the road, when there is a problem, no one has any answers.

I think this approach is short-sighted, They care too much about the right now, without considering the later maintenance, which to me is more important to the bottom line because the later you have a problem, the more expensive it is.

Plus it sounds so re-active to me as opposed to pro-active.

Mark

[Ilja Preuss]

Originally posted by Gerardo Tasistro:
Those values are there for me regardless of your usage or lack of usage.

Fully acknowledged. Please rest assured that it was never my intention to suggest otherwise.

Although Leandro's need for documentation could be questionable. And thus your "what for?" question would be valid.

Gerardo, I'm troubled by this ongoing misunderstanding. The main purpose of the "what for" question was not to question the need for archiving the documentation, but to inquire more information about this need, to be in a better position to discuss the appropriateness of different tools.

Should it be a software UML tool? Well maybe. According to me it should. But then again I could be wrong. But can you question me on that?

Did I do? As far as I can tell, I never questioned your suggestion of a software tool, I merely tried to defend my suggestion of a non-software tool.

So Ilja what is your point here?

My point is that we don't have enough information to tell whether Leandro needed a software tool, so my suggestion of perhaps using a whiteboard, combined with an inquiry for more information about his needs, were not off topic, and not at all driven by costs of the tools or missing education on UML (as you seemed to suggest).

Do you recommend that he just do diagrams on whiteboards and archive photos?

As far as I can tell, I never told Leandro what to do, I just pointed him to some tools.

[Ilja Preuss]

Originally posted by Mark Spritzler:
That is what scares me about Agile, is that it is extreme.

Well, yes, depending on where you are now, Agile Software Development certainly can look scary.

Sometimes you can't get that face-to-face and it bogs down the process and makes it take longer to get things done. It is not efficient in that case. Now, I know they meant the statement in more general terms, but other, those that implement Agile, tend to take it to the extreme and declare no more written communication.

There are probably people who misunderstand the principle to mean that you shouldn't write anything down. But as it doesn't look like you are suffering from this problem, it probably wouldn't manifest for you, would it?

So the Face to Face information sometimes gets lost and difficult to recreate if the two sides leave the company and months down the road, when there is a problem, no one has any answers.

Well, yes, that could probably happen. But before we jump to write down all that information, we need to ask us several questions:

- why doesn't get the information spread in the team by close collaboration, and
- how much would does this problem cost us, and how much would it cost us to write down all the information that *might* be needed?

So we need to find a balance between writing things down, conserving information by other means, and the risk of loosing information.

The presumption of the Agile community simply is that that balance can be much more on the side of spreading information by close collaboration and conserving it in "team memory", "executable documents" and lightweight tools than traditionally accepted.

I think this approach is short-sighted, They care too much about the right now, without considering the later maintenance, which to me is more important to the bottom line because the later you have a problem, the more expensive it is.

I understand where this perception is coming from, but I think it's wrong.

from the Manifesto again:

Agile processes promote sustainable development.
The sponsors, developers, and users should be able
to maintain a constant pace indefinitely.

Plus it sounds so re-active to me as opposed to pro-active.

I'd say that part of it is more re-active than you might be used to - but other parts probably are *more* pro-active, just in ways that aren't easy to accept when you are not used to it.

For example, actively trying to reduce the amount of information that needs to be remembered, and working on having it remembered in more brains instead of on paper, could be seen as quite pro-active.
[ February 02, 2006: Message edited by: Ilja Preuss ]

[Ilja Preuss]

Originally posted by Scott Ambler:
Agilists document, it's just that we focus on high-value documentation. We put a price tag on documentation, and ask our stakeholders to prioritize the development of it. Yes, we treat it like any other requirement. It's the stakeholder's money, they should decide how it's spent, not us.

Well, that is one part of documentation. The other part is what the development team needs, but the stakeholders never would ask for.

Agile teams produce such documentation, too. But probably much less than a traditional team, and in different forms (a team wiki comes to mind, for example).

[Scott Ambler]

On documentation: If you want to invest in technical documentation, then you should be able to justify it to your stakeholders. They're not stupid, they will listen to reason.

On communication: The principle says that face-to-face communication is the most effective way to communicate, it doesn't say that it's the only way that you're allowed to do so. At the communication essay I referenced earlier there is clearly multiple ways to communicate, some better than others. Choose the most effective ways to communicate which get the job done.

- Scott

[Gerardo Tasistro]

Originally posted by Mark Spritzler:

I think this approach is short-sighted, They care too much about the right now, without considering the later maintenance, which to me is more important to the bottom line because the later you have a problem, the more expensive it is.

I totally agree with you and think you hit the nail on the head. Kinda like saying accountants should only know the current balance and not all the transactions that lead to it. After all what really matters is that we have a certain amount of money in the bank.

Documentation is an asset for the stakeholder. It is an x-ray into the system and like you say key in future maintenance. Plus the pair-programming works only if one member of the pair was in the original team.

Reminds me of a certain experiment. Five monkeys are placed in a room. They are fed some suff from a wall door and given bannanas from the roof. Catch is every time they grab a banana from the roof they get sprayed with cold water.

The procedure is done until conditional reflex tells the monkeys not to grab the bannanas no matter how much they want them. At that point one of the monkeys is removed from the group and replaced by another.

First day into his stay with his buddies the bannanas come down the roof. He goes to grab one and gets battered down by the four others. Next day he tries again and gets battered down. Yet no water is actually coming out.

Finally he learns that he doesn't go for the bannanas no matter how much he wants it. At that point another monkey is replaced. The process is repeated and the monkey learns. Eventually all five are replaced and all their replacements have learned you don't go get the bannana.

At that point another monkey gets replaced by a sixth monkey that was not in the original team. He goes, he gets battered and he eventually learns. None of the original monkeys remain. No water is comming out. Yet they are beating the poor thing to death for some bannanas.

Hence the need for documentation.

[Ilja Preuss]

Originally posted by Gerardo Tasistro:

Hence the need for documentation.

It doesn't show the need for documentation, but need for critical reflection on what we are doing. It shows that practices that might have made sense yesterday could be just silly today. That we tend to do things just because we are used to them, because "it is the right thing to do", not because they still provide value.

[Ilja Preuss]

Originally posted by Gerardo Tasistro:
Kinda like saying accountants should only know the current balance and not all the transactions that lead to it. After all what really matters is that we have a certain amount of money in the bank.

No, it's not at all like saying that.

Documentation is an asset for the stakeholder. It is an x-ray into the system and like you say key in future maintenance.

That's an interesting analogy. When a doctor needs to operate on someone, he typically doesn't rely on x-ray from years ago, does he. You also don't have x-rays made of yourself every week, just in case, do you?

Plus the pair-programming works only if one member of the pair was in the original team.

Well, for every software development project, the knowledge of the team is the biggest asset, no matter how much you document. So, yes, keeping the team together should have high priority.

And yes, if you plan on dismissing the whole team and later starting over with a whole new one, you should invest in more documentation.