What document should describe usage of a third party library in a project?

Question

A customer of my employer has recently requested new features for some legacy code, and since the authors of the program are no longer here, I've been assigned to implement the new features.

I've been provided with some high-level documents that are mostly from early stages of the project: the project definition, black-box testing procedures, research analysis of the initial phase of the project, and so on - nothing at a technical level.

The code makes extensive use of a third party library (Lemur Indri) for indexing and retrieval of indexed materials, but there's no documentation of how we use this library, or why it was chosen. I've spent a lot of time just learning about the library itself and how we use it; I feel like this is wasted time.

During a meeting with my supervisor I mentioned that it would have been nice if the developers of our system had written some documentation about the library and how we use it. I told him that it would have saved a lot of time for me, but I couldn't convince him that this type of thing is essential.

I think writing such documentation helps future developers to get a grip on the system and perform modification faster. If there should be such document, what would it be called, or should it be included in one of the design documents?

• Mike Partridge: let me know if my edit lost anything important from your question.

Answer 1

The proper place for this type of documentation is in the code itself. On a side note, documentation is notoriously inaccurate so your best bet, as a developer, is the create the most clear and concise code you can.

Ideally, the 3rd party library is isolated to a single Class or Module so it can be easily understood and documented. If the library seeps into the domain there may also be some coupling concerns that you need to worry about.

Answer 2

All code should include the documentation/comments necessary to make it clear.

That includes documenting how and why a library was used. One need not repeat the documentation for the library, but if understanding the code's use of the library is not possible without hours of scouring documentation, then you absolutely should include some information on how it is being used.

The place for this is the core documentation for the code; it shouldn't be separated out simply because it is about a library.

Answer 3

All the above answers are fine. One missing item, though, is the information necessary to track (at the very least) security updates and bug fixes in the library:

• Any possible contact information (mailing lists and web sites).
• End-of-life constraints (if any).
• Specific instructions on validating the library's results and performance in your environment after an upstream update (numerical results may change either because of regressions or bugfixes/performance shifts - you have to know which test cases to update and which should stay the same).