[LarryL]

> graphics and charts, do you use any specific tool?

Usually, I used Visio, not really by choice but because it was available and sometimes used by other coworkers (usually for the specs flowcharts). There was another tool available, that was used in one of those companies, it was better than Visio, but I don't remember the name, unfortunately, due to a insufficient number of licenses, I could not use it.

When I do such stuff on my Linux box, I use various flowchart/diagram tools like Dia (and another one whose name I forget). I've also experimented with various text-based solution (LaTeX-based & the like), but with mitigated satisfaction: those solutions where too heavy & cumbersome for my use case.

As you wrote, those ARE time consuming and have the usual update problem. But that cost is really offset by the benefit of clarity. When _I_ gave a module to the testers team, I gave them a brief (15 to 20 minutes max) presentation and my documents & usually never heard again from them (except when they found a bug of course), while with the other modules (made by my coworkers), I saw them asking for more information all the time...

> EDIT: came up with a better way to put it: documentation should deal with what a system does, why and where, then how it achieves so in a broad sense, and finally deal with the implementation details (which is the only part we are kinda handling nowadays, as you explained).

You describe _exactly_ the problem. And I've been fighting hard to make that simple idea enter in my coworkers -thick- skulls, but with not much success: they often do acknowledge the problem, but either don't care (disgruntled or not professional) or are too lazy or are overworked and take shortcuts, not realizing that medium and long-term they would in fact GAIN some time... As for the management, I've lost all hope, no amount of discussion can enlight them (they only see "THE CODE").