I don’t know if I am more relieved or frightened to discover that astronomers have even less clue than software engineers on how to describe their subject to beginners.
I borrowed The Moden Amateur Astronomer, ed. Patrick Moore, from the library. It’s one of a series with the general title Practical Astronomy, and according to the blurb,
If you already own an astronomical telescope and want to know how to use it to the best effect, or if you are thinking about buying one and are wondering where to start, then this is the book for you.
The four pages of Chapter 2, Buying a Telescope, by Patrick Moore himself, are clearly written and left me with a clear picture of the pros and cons of different kinds of telescope and what to look for if I was buying one, but every other chapter gets bogged down in details that I (as a beginner) don't understand rather than explaining general principles, and shows no awareness of what I need to hear and what order I need to hear it in if I am to make any progress.
In a section on photography in the chapter on Auxiliary Equipment, I read that “…the most important features to bear in mind are the accessibility of the focus and the vignetting of the light cone.” Vignetting of the light cone, eh? What is that exactly? Is it something I should be avoiding like the plague or something I can’t do without? I read on and discover that it is “one of the most irritating problems in deep-sky photography and can easily ruin an otherwise excellent photo.” Yes, but what the hell is it? How will I know whether my pictures suffer from it? It turns out that I can avoid it if I buy “a low-profile focuser with a draw tube of at least 2 inches in diameter.” So all I have to do to clear up the subject is find out what a focuser is (and where I get one), and how I recognize a low-profile one. (As opposed to what? High-profile? Low-fullface?)
I searched in vain for a straightforward answer to these questions, though I did learn that “to determine the optimum focuser and secondary mirror size for your system, a simple ray diagram, showing the light cone, needs to be drawn,” (so simple that there is no need to supply an example).
Turning to Chapter 9 on Astronomical Spectroscopes, I read in the first paragraph that “75% of all our knowledge in astrophysics derives from observing spectra.” This sounds exciting, but the rest of the chapter has little to tell me on what this 75% is made up of. It provides me information like the following:
The wavelength shift of the observed stellar lines when compared with their rest wavelengths gives the star’s radial velocity via the Doppler formula
v = 3 × 105((λ0 - λ1) / λ1),
where v is the radial velocity in km s-1, λ0 is the observed wavelength of a line and λ1 is the rest wavelength of a line,
but nowhere bothers to tell me what the radial velocity of a star is or why I should care about it. The same treatment is given to all the other subjects touched on in the chapter, like emission line stars, Hertzsprung-Russel diagrams, and Fraunhofer lines.
I could give many more examples from this chapter or almost any other. Compared to this book, Linux HOWTOs are a model of clarity.