more documentation improvements, especially package description