| Ideal documentation has interlinked sections that serve different purposes. For instance right now I am writing up a report on a research project I did a year ago (shouldn't have waited) and now facing the problem of running the scripts. Some of them are well documented but some aren't. Whether it is you or somebody in your pod who has to do it, there is a need for "runbook" documentation so you can do tasks such as building and deploying software correctly and easily. There's also a need for reference documentation that explains everything systematically, even that tends to need multiple forks -- for the Spring framework there is all of the Javadocs, but the Javadocs are not sufficient to explain the concepts that Spring is built around. Then there are the pedagogical examples that make doing something tricky look easy and link the implementation to the concepts involved. I'd point to the Python documentation as a particularly good example. I never feel tempted to look outside the official Python documentation to look up anything that's involved in the core language. Somehow I don't find the documentation for pandas to be effective, largely because I perceive the ways of doing things in pandas to be idiosyncratic, so I find myself looking up answers on random web sites a lot more often than I feel comfortable with. If I used pandas everyday I might feel differently, but I usually end up doing a burst of data analysis work for a few days and then go a few months w/o using pandas. |