Provide Architectural Documentation #19
Description
It wasn't clear, neither from documentation nor from code and neither from automatic tests, what methods of access support the order-preserving iteration.
Consider also the explicit reordering, such as https://docs.rs/indexmap/1.6.1/indexmap/map/struct.IndexMap.html#method.sort_keys and https://docs.rs/indexmap/1.6.1/indexmap/map/struct.IndexMap.html#method.sort_by
The docs mention using HAMT and trie, but I couldn't verify it from a cursory look at the code. IMHO there should be a mapping between the high-level documentation, such as the mention of HAMT, and the relevant code. Imagine going to Google Maps, zooming in and seeing entirely different location. The lack of connection or mapping between the different layers of documentation is similarly disconcerting. In order to be reusable ( https://youtu.be/pW-SOdj4Kkk ) software needs to allow for gradual zooming in and our, from architectural overview to code and back, IMHO.