While reviewing our excellent latest draft, I have experienced a growing concern that I feel is serious enough to bring up now to the TC as a whole, rather than as a single comment in an issues spreadsheet. I am also concerned that if we do not address this issue as soon as possible, it may prevent our spec from reaching OASIS memership approval.
The issue: The organization of information in our spec is very poorly organized, leading to multiple repetitions of concepts and descriptions that make it very awkward to read and absorb.
As one example of many, we discuss the notion of "service visibility" in at least 2 places: Line 195, and line 282. This not only makes for awkward reading, but also risks inconsistencies in descriptions of concepts throughout the spec due to the need to maintain descriptions in multiple places, and syncronize them.
I therefore propose that we examine this aspect of our spec, and work to "componentize" our spec in a more organized, easy-to-absorb fashion. I would be very happy to work on a proposal for improved organization that will help us meet this goal (i.e. I am not merely suggesting this without being willing to take on the responsibility of making it happen).
Booz Allen Hamilton
700 13th St. NW
Washington, DC 20005