3 ms·
> From official documentation I found about 20 pages of content to describe a 1 page financial message. It's an absolutely horrific problem in graphic design to
by Jtsummers 6y ago
> From official documentation I found about 20 pages of content to describe a 1 page financial message. It's an absolutely horrific problem in graphic design to relate 5% message to 95% documentation.
This depends. If that documentation can be reused by other participants in the development process, it's very useful. Perhaps a bit excessive, but useful. With that you could hand it off to the recipient of the message and they can implement their own processing in their own language and applications. If you handed them your implementation could they use it directly or easily port it to their own target system?
And what was that documentation? Does it add real clarity or not? I used to work on a project which had an absolutely massive message spec document. Over 1k pages (I know 1k, I think it was closer to 2k but can't find it online for free to verify), and the implementation (of the message data structures and primary functions) was certainly much less than that.
But that documentation told us the exact memory layout expected. Messages which in C may have been described with a 20 line struct definition could mean 18+ fields if reasonably formatted. Each field has expected values/types (that the C int type doesn't sufficiently specify) that need to be documented. Like "This 4-bit field can take a value from 1-10, here are the meanings of each:". Now that one line in C is at least 11 lines in the spec. So about a 1:10 ratio of code:documentation was reasonable for this situation.
- PaulHoule 6y agoThe ultimate answer is that different information is meaningful to different consumers. In the case of the financial message, fully "understanding" it could involve understanding complex regulations in multiple jurisdictions. (e.g. "is this message valid" is a question for accountants, lawyers, other subject matter experts, etc.) Those people couldn't care less about the ISO 8601 date format but if you don't understand the subset of that format used in the specification you may have trouble parsing messages and will likely have problems generating well-formed messages (though the SME's could care less) The beyond state-of-the-art goal that a group I am in is looking at is how to trace from one end to another; the third bit of the fifth byte is a boolean flag, but it exists because of 'that requirement', here are all the definitions you need to understand 'that requirement' and do it at interactive speed with 10 people in the bullpen to create "task forces" that can function at a vastly superhuman level (think IQ 500) at maintaining and implementing specifications.