| Some more detail on this: The starting point for BRender was a sequence of software rendering experiments that grew from 'never doing it like our hand coded asm real mode x86 renderers ever again'. There were various diversions, eg: an achingly beautiful plane sweep that only rendered the visible parts of each output scanline, whilst murdering the cache so comprehensively that there are likely still lines waiting to be filled even now. Fortunately, to get the FX Fighter team going with something stable whilst debugging continued, I knocked up a Z buffer implementation, and was given a sharp lesson on caching when it blew all the previous attempts away (notably with consistency of performance). Arriving at this point we figured there might be a product in it and looking at our own interaction with other libraries, it was clear that a manual was key to this. If I remember correctly, the API was a negotiation between myself proposing designs, and Crosbie Fitch documenting it - pushing back with ways to make things easier to explain. It worked out very well, and we took it into later Argonaut hardware projects. The hardware guys had enough tools to do frame capture and replay from various games/apps at a low level, so were not desperate for a full software stack. The clients had very particular views about how APIs should look, depending on planned uses, in house style, compatibility etc. We would negotiate the API documentation back and forth - including lots of sample code. This sample code was important, (and BRender would have benefited from more of this). I took lots of real use cases, then wrote proper code to implement them against the proposed APIs and included them in the docs as tutorial and example code. Importantly - they were a representative sampling of the anticipated uses (not just the easy ones), they were not 'handwavy' and included all appropriate resource management and error handling, and they had to read well on the page. As the API negotiation continued, so the examples and tutorials got updated. This process also had the benefit that we only started investing in client specific software development once the project had got enough momentum (typically committing hardware NRE). |