A perpetual problem with scientific software is that much of it starts out as one-time scripts written to analyze a specific piece of data, and then it gets released into the wild as The Way To Analyze This Type Of Data. A closely related problem, which affects repositories of scientific software, is that a kind of informal API develops among the developers and users (who are initially the same people) of packages within the repository, without ever being really documented in a way that makes sense to people who have not been involved in the development. What documentation there is tends be rather
Not to break my arm patting myself on the back, but I have to say that my years of industry experience in writing end-user applications, and managing a development team made up of people who had all joined the team at different times and had to understand what was going on, taught me a lot about how to write good documentation. Industry programmers could learn a lot from academia about how to make software run better, because scientific users have to squeeze every possible bit of performance out of every processor cycle. Academic programmers could learn a lot from industry about how to write documentation that allows people to use that performance without wanting to tear their hair out.