The org.apache.lucene.index package level javadocs are sorely lacking. They should be updated to give a summary of the important classes, how indexing works, etc. Maybe give an overview of how the different writers coordinate. Links to file formats, information on the posting algorithm, etc. would be helpful.
See the search package javadocs as a sample of the kind of info that could go here.