Mike Treseler said:
I like to demonstrate this "idea behind it all" in
working and well-commented testbench procedures.
It is a rare exception when anyone other than the
developers care about this level of detail.
One problem with commented testbench procedures though is that those
procedures are only testing the certain subset of conditions under which the
thing has been tested and verified which is many times a subset of the
entire ways that the design will actually operate out in the wild.
If you follow the test driven development methodology then your testbench
(and therefore the commented code) will be created first before the design
so it would be available to the other developers. If you create the design
first and then the testbench for that design, then the documentation for
those other developers might not be ready when they need it when performing
concurrent design.
<soapbox>
Personally, I prefer creating a design specification. High level design and
architectural decisions are made before design or testbench code gets
written, putting those decisions into some tangible form and keeping that
document up to date are not that hard to do. Plus, by creating such
documentation, you can have actual live links to reference information that
would be useful to whoever it is that would read the document.
After the fact documentation is always tedious, dull and nearly pointless.
Presumably 'somebody' needs information on how your design is supposed to
work so that they can create their design so that the two can be integrated
into a final system (unless of course that 'somebody' is yourself). So,
except for the one man show, this after the fact documentation is almost
guaranteed to be too late so even if the only audience is the developers,
those developers do need the info, they need it in a timely manner to do
their part and unless you like to answer phone/e-mails regarding how it
eventually will work (and probably giving conflicting answers over the time
period that you're creating the design), the design spec provides the common
ground for all, filling it out more of the details as one goes along, gives
everybody the up to date info that they need to do their job.
Using a tool to extract this information after the fact is generally more
work than to have simply put that exact same information into a design
specification.
...and, if I ever have to work for Nico,
I will at least make it through the first day.
(but probably not much longer
Ya might've even missed out on the interview
Kevin Jennings
