See figure 1

One of the first lessons you learn in grad school is that your text book(s) is/are as valuable as a paperweight. At least in the hard sciences, the field tends to move fast enough that, by the time a text book is published, the information within is either incomplete or inaccurate. Consequently, you'll spend more time reading the relevant journals for your field than any text book, and new information is introduced through review articles.

The long preface is only to introduce Shamus's post on the problems he encounters in the tech world, writing support documents and other technical documentation. Though many of his examples are angled towards programming or coding languages, the general principles are by no means unique to his field.

I find often that the scientific literature suffers from the problems Shamus describes: No explanation of technical terms, assuming a higher level of knowledge on the part of readers than is warranted, assuming a high level of knowledge in related (or not) fields, over-complicated examples, building too steep a learning curve, and so on. One problem that is more unique to this field is the use of self-serving examples. That is, all of the "relevant" work referenced by the author of a review is to his (or their) own work in the field. While this might be appropriate if you're one of a handful of people who actually study the topic at hand, it usually gives only a narrow impression of the work being done in the field, and thus not appropriate for a "review."

One idea that Shamus introduced that I would love to see implemented more fully in the scientific journals is better use of the electronic medium. Everything that is published on paper also is published online as a PDF. Journals like Science usually affix a "title" page to it, with links to the supplemental material on the web (additional figures, movies, and whatever else the authors considered important enough to include but not critical enough to warrant space in the paper). However, taking this further would be an incredible step in bringing science into the age of the internet.

In a review article, what if certain terms or phrases were hyperlinks to either a "dictionary" of terms or to futher review articles on the specific topic? What if the citations at the end of the paper were themselves hyperlinks which would take you to the reference? What if each of the authors' names were hyperlinks to other articles they have published? When a technique is not fully explained by said to be done "as previously described," either link to where it was described or to a database which explains the principles such techniques.

While I realize this might seem like a lot of work to put into a simple PDF journal article, this would be insanely useful to all sorts of people. And these are just the hasty suggestions of a graduate student . . . I'd love to see what sorts of suggestions actual experts might come up with.