Fog Creek Software
Discussion Board

Crash course in SW Project Management?

Here is the immediate situation.

My client is a SW product company. The owner is also the main architect of the company's products. The employees who code are inexperienced to medium level people - the most experienced of the bunch has the same 1.5 years of experience, repeated about 6 times. Hiring philosophy is definitely indians, not chiefs.

The owner is frustrated because he wants to "design" in advance the many (dozens of) classes that are needed for his product, and then delegate the actual coding to his coder employees.

The owner has tried to disseminate this specification knowledge by writing up enormous Word documents containing lists of the attributes of each class, form, control, or source file.

Several things happen when he does this. The coders are stuck at dead center until they are talked through the meaning of the specs for individual classes. The code that is produced is generally not what the owner expects or needs. Rarely, does anyone hit the mark on their tasks as delegated by this method.

I've read his documents. I believe that many of the deliverables he needs should be doable by the people he has, if the requirements could be communicated clearly. The docs as such are "pretty good" but lack a lot. For instance, he needs class hierarchy diagrams of classes being discussed (now lacking), and the nomenclature of the various pieces of the system change back and forth from colloquial names to specific class names and instance variable names of classes, members or variables. Admittedly, capturing all the detail of each class in a complex task like this is Sisyphean undertaking.

The development language is Delphi, BTW.

So, the questions I have are:

What are best practices prevailing in industry for disseminating this level of detail on a development project? Rather, what resources would you recommend for further reading on the type of problem described here?

Are there any SW project management tools in existence that would allow a large OOP project to be laid out conceptually, and would generate class user documentation, hierarchy charts, etc? Ideally, it would be great to have a program that would allow all the design criteria to be entered and then have a phase that allows an inheritance chart and function and class specs to be printed out.

Integrated project and class management tools for this would be nice, too.

"Be nice" - I'm a developer and I'm quite new to this. I just told him I would try to help.


Bored Bystander
Monday, October 27, 2003

Not sure exactly, but are you aware of Enterprise Architect?:

I assume Borland has some nifty stuff that's much more expensive and more appropriate for real enterprise-level work.  Enterprise Architect is very inexpensive and may be what you're looking for.

Herbert Sitz
Monday, October 27, 2003

Visual Studio ?

Monday, October 27, 2003

Sorry - bad advice - visual studio  wont help at all, I've used some rational stuff for this but it's kludgy and expensive.

I look forward to any suggestions too.

Monday, October 27, 2003

This sounds like the sort of thing you use Rational Rose or some such UML design tool for.  Of course, it's expensive and kludgy, as already noted.

This would give you class hierarchy diagrams, class specs, etc.  But you might still be missing what you need.  It will generate C++ skeleton source code.  Don't know if Delphi is available.

Monday, October 27, 2003

So far, Herbert Sitz's recommendation for Enterprise Architect looks promising. I downloaded the 30 day trial. One thing that makes it look good for us is that the corporate version can be run against a MySql server, so we can share the designs on & offsite.

I think what we basically need the most right now is a good way to capture documentation for the classes. Beyond that, it comes down to how well the overall project has been thought out.

I also checked out Modelmaker, a CASE tool for Delphi only.

I'll check back with progress.

Bored Bystander
Monday, October 27, 2003

Enterprise Architect has its roots in Delphi though it's now available for other environments.  EA's and ModelMaker's feature sets overlap to a certain extent, but EA is definitely geared more for high-level design and documentation and ModelMaker is better as a lower-level tool for use while coding.  At least that's a general distinction between the two, and both seem to be pretty highly regarded within Delphi community.

Herbert Sitz
Monday, October 27, 2003

Around here we have a two step process, utilizing Word and Visio.

Firstly, we create a 'Requirements' document in Word.  Its a 1 - 2 page summary of the module being developed.  We have 5 sections in the document designed to give the developer a 5000 ft view of the problem.  Everything in the document must be presented in point form.  Easy to write, easy to read.

Secondly, we create a UML diagram for the problem.  In addition to the class diagrams, it must include a sequence diagram.  A picture is worth a 1000 words, as they say.

We have found this process very effective because:
  *  No one minds writing a 1 - 2 page, point form doc
  *  No one minds reading one either
  *  Easy to communicate with developers AND managers

Some limitations:
  * Visio has its problems --> no autogenerate of code if you aren't using .NET or similar MS technology (we use Delphi sometimes too)
  * Its not a fancy case tool, so you must already have a good source control process in place, otherwise everyone has out of date docs


Monday, October 27, 2003

Looks to me like this marketplace is ripe for someone to write a killer app.
Monday, October 27, 2003

I agree with Mark ...

We looked around forever for a tool that would suit our needs.  Our team has co-op students through to 10 year vets, so finding some common ground for all of them was tough.

The method I presented above is very much a 'Keep It Simple, Stupid' approach, so I can't help feel that we aren't leveraging some of the power of the better UML/Case tools.

Everything we looked at however, pretty much blew away the junior staff, the ones we were trying to help.


Monday, October 27, 2003

Don't worry about the tools yet.  Try working on a better process.  Designing the whole thing up front is just asking for trouble.

Try a little reading: Software Project Management by Royce.  An iterative development model, keeping your documentation requirements in check, and above all, seeing problems, not symptoms.

And, IMHO, good programmers are made, not hired.

H. Lally Singh
Monday, October 27, 2003

Oh yeah, another comment on processes: don't go overboard.  Figure out what you need & do that.  If it isn't enough, do a bit more.  If it's too much, calm down. 

One problem with the software engineering literature is its obvious super-large-DoD-project focus: they're the ones who spend the most money on SE research.  No point in trying to go SEI level 5 when you've only got 20-30 programmers.

H. Lally Singh
Monday, October 27, 2003

I would like to suggest that the owner / architect needs to consider a different way of working.

He should be able to communicate intentions to his people without detailed specifications, then trust them to implement appropriately. If necessary he should develop procedures to develop this capability amongst his developers.

The way we do it is that the core requirements for modules are specified, and then implementation left to the developers. Implementation will include adding classes or functions as required, and changing core API specifications if appropriate.

Monday, October 27, 2003

I agree -- if the owner works like that, then the employees will always remain mediocre / unknowledgeable.  It is good to have someone who has technical leadership, but what you describe sounds like he thinks everyone else's ideas are inferior, and that he should design the whole thing and send it off to his underlings.  To have the company grow, it is necessary to spread knowledge beyond one person and to delegate responsibility.

I'm surprised that this actually works.

Monday, October 27, 2003

I'd suggest a coupla things:

* Some higher-level documentation like functional specs, requirements or overviews of class interaction would be helpful for the programmers. They'd make less mistakes if they knew _why_ they were implementing a certain class, not just how.

* Jeez, show a little faith in the staff! They may be inexperienced but treating them as meatware Word->Delphi translation tools isn't going to make them get any better. Ease off on speccing the every class down to the last method name. Confine yourself to class specs for the interfaces between modules and leave the rest to the programmer's discretion. Conquer your fear that this will cause them to stuff things up by using the time you've saved writing specs to write unit tests for their code.

Andrew Reid
Monday, October 27, 2003

Obviously the life of a consultant isn't evident. So, you guys who are tearing apart the owner's methods disregard several important things:

He asked for my help.

He's never but ever asked for anything from me in the past except coding support.

He's not obliged to take any of my advice.

He's not an IT professional by background. He backed into software development.

The owner does believe in staffing with non-chiefs, IE, indians. He understands that someone highly ambitious would get bored and leave. He wishes to minimize turnover.

I will not change the owner, his practices, nor his idiosyncracies. At least not immediately.

If the owner is not comfortable with whatever I recommend, he won't use it/do it.

If he cannot find an application for the things I am willing to do for him, I will not be working there.

He has made a *lot* of money doing things the way I have described.

Think: "evolution", not "shitcan everything the guy with the money has done for the last 10 years."

It's business, guys.

Bored Bystander
Monday, October 27, 2003

Ok, analogy time.

When the U.S. Marines are tasked to take a hill, the general in command says "take that hill". He doesn't say: "I want you to take that hill by sending 1 platoon up that road at 5 miles per hour, and 2 more up that gully at 6 miles per hour", etc, etc.

The reason they don't work that way is twofold: first you need someone to keep their eye on the big picture, and second, the people best suited to making decisions in the heat of battle are those at the point of the knife.

Of course, if you don't teach your grunts which end of the rifle to point at the enemy, then it doesn't matter how good your plan is, right?

There's also a reason the military (well, the marines anyway), doesn't try to plan down to the last bullet: the plan never survives contact with the enemy.

I'm not sure how this architect has managed to survive to this point but I'm sure HUGE amounts of wasted effort were involved. Go get him a book on agile development methodologies, tell him to sketch out a rough architecture, and then get him to lighten up a little.

Monday, October 27, 2003

[Obviously the life of a consultant isn't evident. So, you guys who are tearing apart the owner's methods disregard several important things:

He asked for my help. ]

Oh, well then.. :)

This won't generate code or anything, but one tool you might want to look seriously at is a wiki. Get the document out of the Word format and into a wiki where everyone can access it/play with it/change it as necessary. It will also help you link related pieces of information.

I know it's not code generation. Best I can do, sorry.

Monday, October 27, 2003

Bored, given the time it takes him to write these word docs, and the time it takes the programmers to read them to get a sufficient understand of the material, why not have the boss give a presentation to the teams on the high level architecture things they will be responsible for.

It shouldn't take MORE time to do this.

Also, I think starting a Wiki would be great, though the initial data dump might be a pain, but a competent temp could do it. This way someone could comment on a particular class or section, procedure, method, call, etc. and the comment would remain with it, and it would be completely up to date at all times. No re-disseminating the information when revisions are made.

The Wiki could have some custom code to relate functions and sub functions, etc., allow the uploading of images and files for diagrams, lets you query so you can get several related items on the same screen for printing or quick reference and so on.


He writes the Word Doc as usual, or directly works in the Wiki. A Wiki has the added benefit of being two-way communication. He can start to understand where problem areas are based on the comments, making him more effective at architecting these applications.

He gives a presentation to everyone on day1 about the high level architecture. Later that day, or on subsequent days he gives a presentation to different teams about their components & responsibilities and how he expects them to work.

On an ongoing basis, everything is maintained in a Wiki, which allows everyone to access the same data, and make comments and revisions as needed, all in "real time."

UML & diagrams would be nice too. Comments in the code could have links to the Wiki, the Wiki could refer to lines of code, and maybe entries can be tied to particular revisions in the CVS. (More custom code?)

And there's your killer app. :P

Another step further would be to make the Wiki really compatible with the code & architecture, integrated with the CVS, capture comments in the code, and lets you import bits of the Wiki into the code as comments - updates to one would reflect in the other, and to do that "round trip" thing Rational Rose does.

Maybe I should start a software company. Move over Fog Creek, here comes Hudson River Smog.
Monday, October 27, 2003

> What are best practices prevailing in industry for disseminating this level of detail on a development project? Rather, what resources would you recommend for further reading on the type of problem described here?

I'd recommend and the others at

> Are there any SW project management tools in existence that would allow a large OOP project to be laid out conceptually, and would generate class user documentation, hierarchy charts, etc?

The salaried staff. You said "The docs as such are pretty good but lack a lot"; how about getting the coders to write the *detailed* design from his overview ... that would offload him, let them start thinking about and understanding it, let ehm present to him a design they're happy with and let him review/correct their work before they start coding.

To work around the "from colloquial names to specific class names" problem, use the compiler ... why write a "design" in english when you could be writing compilable header files. Does Delphi have a reverse-engineering tool to let you generate diagrams from header files?

Christopher Wells
Tuesday, October 28, 2003

"Does Delphi have a reverse-engineering tool to let you generate diagrams from header files?"

Here's a freeware tool for Delphi that does what you're asking, I think:

I think ModelMaker and Enterprise Architect both also do this.

Herbert Sitz
Tuesday, October 28, 2003

I'd get him all excited about Extreme Programming.

Simple Design & Story Cards, Specifically.  Why design a whole system over the next 12 months, when you can having something working in 2 weeks? (It just doesn't do much?)  That way the testing burden moves from "A CRAP-LOAD OF TESTING threatening to make the entire project late" in the last 2 months to testing for the last 11 months.

IF there's code problems, they can be discovered and fixed early enough in the cycle to be less of a problem.

JMHO ...

Matt H.
Tuesday, October 28, 2003

*  Recent Topics

*  Fog Creek Home