Add row/column-major order documentation

README.md

@@ -16,7 +16,7 @@ provides an interface to the HDF5 library for the Julia language.
 
 ## Changelog
 
-Please see [HISTORY.jl](HISTORY.md) for the changelog. Most changes have deprecation warnings and thus may not be listed in this file.
+Please see [HISTORY.md](HISTORY.md) for the changelog. Most changes have deprecation warnings and thus may not be listed in this file.
 
 ## Installation
 
@@ -109,6 +109,12 @@ There is no conflict in having multiple modules (HDF5, [JLD](https://github.com/
 [MAT](https://github.com/simonster/MAT.jl)) available simultaneously;
 the formatting of the file is determined by the open command.
 
+## Reading Python/C written HDF5 files
+To read a multidimensional array into the original shape from an HDF5 file written by Python (NumPy) or C/C++/Objective-C, simply add the following line after reading the dataset `dset`:
+```julia
+dset = permutedims(dset, reverse(1:ndims(dset)))
+```
+
 ## Complete documentation
 
 The HDF5 API is much more extensive than suggested by this brief

docs/src/index.md

@@ -125,6 +125,16 @@ g["mydataset"] = rand(3,5)
 write(g, "mydataset", rand(3,5))
 ```
 
+## Row- and column-major order
+
+There are two methods, [row-major order and column-major order](https://en.wikipedia.org/wiki/Row-_and_column-major_order), for storing multidimensional arrays in linear storage. Multidimensional arrays in Julia (and Fortran) are stored in column-major order, while other languages including C and Python (NumPy) use row-major order.
+
+To read a multidimensional array into the original shape from an HDF5 file written by Python (`numpy` and `h5py`) or C/C++/Objective-C, simply add the following line after reading the dataset `dset`:
+```julia
+dset = permutedims(dset, reverse(1:ndims(dset)))
+```
+
+Note that NumPy arrays are row-major by default, but NumPy can use either row-major or column-major ordered arrays. For more details on this topic you can refer to [this issue](https://github.com/JuliaIO/HDF5.jl/issues/785).
 
 ## Passing parameters