[asterisk-dev] Feedback requested for future 1.6 API documentation

[Jeff Peeler]

Last year in May I authored a document detailing all of the API changes from 1.4 to 1.6.0 (doc/api-1.6.0-changes.odt). At that time it was thought that we would be able to keep the API frozen for all releases after 1.6.0. This rigid requirement has turned out to be too hard to accommodate. The plan now is to continue documenting the API changes from one release to the next. This decision poses a few questions:

What format should be used? Both the file format and the content layout should be considered. I originally chose an OpenDocument text simply because it wasn't planned to ever be updated. I encourage everybody to take a look at the existing document to get an idea of what might should be included.

Who is going to be responsible for updating the document(s)? If the number of changes between releases are small, it might be best to just let one person to do it. Or perhaps the developer making the change would also be the one to best explain it.

I am also pondering whether or not a script to extract the API differences would be a welcome addition. The script could also help enforce the chosen format. Whether or not this is worthwhile depends on the above questions.

Thoughts?

-- 
Jeff Peeler
Digium, Inc. | Software Developer
445 Jan Davis Drive NW - Huntsville, AL 35806 - USA
Check us out at www.digium.com & www.asterisk.org