- Sep 29, 2004
- 18,656
- 67
- 91
We are currently using a hellish API for Java. It is poorly documented so we are constantly having lessons learned with the API.
To start, we are developing in Eclipse.
The root problem is that we are doing all sorts of discovery on an API and everything is tribal knowledge right now. Al knows this, Bob knows that. And a year later, Al knew this and has a vague recollection of it .... yadda. I can't wait for these people with tribal knowledge to leave (one is a contractor).
To be clear, the Javadoc, if it exists on this API is horrible. And even when it is not, trial and error is often required to truly understand it. And to make matters worse, new engineers on the project have to learn everything others have already learned. And sometimes they end up solving things differently. Sometimes better, sometimes worse. (I'll refrain from discussing all the damned wheel reinvention that is probably occurring)
There are ways to handle this.
Option A: Create a Proxy project that wraps the classes of the API. It sounds daunting but should work most of the time.
Option B: Word Document or similar.
Option C: Open source project that handles this situation. I have no recommendations.
Option D : Whatever thoughts people here have.
To start, we are developing in Eclipse.
The root problem is that we are doing all sorts of discovery on an API and everything is tribal knowledge right now. Al knows this, Bob knows that. And a year later, Al knew this and has a vague recollection of it .... yadda. I can't wait for these people with tribal knowledge to leave (one is a contractor).
To be clear, the Javadoc, if it exists on this API is horrible. And even when it is not, trial and error is often required to truly understand it. And to make matters worse, new engineers on the project have to learn everything others have already learned. And sometimes they end up solving things differently. Sometimes better, sometimes worse. (I'll refrain from discussing all the damned wheel reinvention that is probably occurring)
There are ways to handle this.
Option A: Create a Proxy project that wraps the classes of the API. It sounds daunting but should work most of the time.
Option B: Word Document or similar.
Option C: Open source project that handles this situation. I have no recommendations.
Option D : Whatever thoughts people here have.
Last edited: