I absolutely agree and this is a problem that a lot of open source projects face (Haraka is not alone in this). In part it comes down to the fact that most open source isn't worked on full-time, and so documentation often takes a back seat to getting your feature-du-jour working.
But absolutely we could all use some improvement in these areas.
Yeah, just to be clear I'm not bitching at maintainers, just giving the perspective of a potential company wanting to use a library. Though usually I do try to follow up if I think the software/lib is really nice, but it's often on a personal level, not for my company.
Documentation is pretty boring to write,and not as fun as feature-du-jour, but may be there could be some guidelines about what a basic documentation should have, specially with GitHub it could be straight forward to have a Markdown template for basic doc (Installation, FAQ, Requirements, Contact points, ...), I know I use one.
But absolutely we could all use some improvement in these areas.