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

[Mark Michelson]

Jeff Peeler wrote:
> 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?
> 

I'm willing to bend to whatever format is jointly decided upon. I think that as 
far as who updates the document, it should be handled the same way that files 
such as CHANGES and UPGRADE.txt are handled currently. That is, if you make some 
sort of change to the API, then you are responsible for documenting what the 
change is and why it was made. The best reason I have for this is that the 
person making the change will likely be the best to explain exactly why the 
change was necessary.

Mark Michelson