What tools do you use to outline projects?

I use GraphViz if I need to sketch out such simple diagrams - the DOT language is lightweight and differs very well when I compare versions of the diagrams.

I wrote about this with an example a few months ago with an example showing a more complex architectural diagram.

I have also added a blog post with a larger diagram that shows a large flow of the program to give an idea of ​​how the GraphViz flow can be composed. I don't have time to obfuscate all the text, so just put it there like a low-res image to give the impression of architecture without being able to zoom in to see the details readable.

This diagram was compiled by hand after a bunch of grepping to get it up and running. To avoid too much ridicule, here are some excerpts of the DOT text that the diagram generates.

digraph windows {
 rankdir=LR
 label="Windows Invoked\nby controls and menu items"
 node[fontsize=12]

/* ENTRY POINTS */
 wndMainMenu[shape=box color=red fontcolor=red]
 DEFAULT_WINDOW[LABEL="DEFAULT\NWINDOW" shape=box color=red fontcolor=red]


/* WINDOWS */ 
 node[shape=box color=black fontcolor=black style=solid]
 App
 wndAddBill [label="Add Payable\nwndAddBill"]
 wndAddCustomer [label="Add a Customer\nwndAddCustomer"]

...

/* WINDOW INVOCATION */
 node[shape=oval color=blue fontcolor=blue style=normal]
 edge[fontsize=10 style=normal color=blue fontcolor=blue]

 wndPayBills_bvlNewBill -> wndAddBill 
 wndAddCustomer -> wndAddCustomer_save001
 wndManageDrivers_bvlNewCustomer -> wndAddCustomer 

      

        
        
        
      

    

alt text http://www.aussiedesignedsoftware.com/img/WindowLaunchesZoomedOut.png

For anything related to documentation: Wikis, Wikis, and more! Easy to read and, most importantly, easy to update.

My favorite: Trac (much more than just a wiki)

Are there any means to describe the flow of a program?

Your best comments ("The program is running") can be expressed using a "flowchart".

Your bottom comments ("Background Service") can be expressed with a "data flow diagram".

I am not using flowcharts (I do not believe they add value over the corresponding pseudocode / text as you wrote it), but I do like data flow diagrams for top-level display (i.e. data stores / formats / locations and data processing / IO steps). However, data flow diagrams predate the UML, so their descriptions are not available on the web.

I like sequence diagrams for anything in the OO field. There are some good ways to create sequence diagrams without spending all your time getting polygons around.

First, there are some sequence generators that accept text input. See WebSequenceDiagrams.com for example .

There's also a nice Java based tool that takes text input and creates diagrams. This is good for integrating into your build process because it can be called directly from ant.

If something is difficult, I like the pictures, but I try to do it by hand on paper, so I can visualize it better. Boards are great for this.

I break down a large or complex application into smaller pieces and develop them on paper so I can better understand the flow between the pieces.

Once I have a flow between the executed parts, I can better design each part separately, since each part is its own subsystem, so I can change languages ​​or platforms if I want.

At this point, I just start working on the application and just work on one subsystem at a time, although the subsystem may have to be decomposed until I have a piece to keep in mind.

• Use cases
• Action diagrams
• Sequence diagrams
• Machine State Diagrams
• Class diagrams
• Database diagrams
• Finally, after they are done and the project is well defined, in Microsoft Project.

I like to maintain this flow as it documents well, defines it clearly and explains easily, not to mention that it is just a good process. If you don't know what it is, take a look at my answer here for more information as well as some links.