Subscribe Bookmark



Nov 10, 2016

Just the Facts, Ma'am...

Now that JMP Genomics v4.1 has gone to production, I have found a little time to catch up on my reading. As I was perusing a recent issue of the Proceedings of the National Academy of Sciences (USA), I was struck by the fact that the traditional limit of 5 pages has been scrapped and that articles of 6 or more pages have become common. Papers have grown as investigators try to pack as much information as they can into more and more space. Even authors of Science reports, which have traditionally been limited to 2500 words, get around page limitations by regularly including links to Supporting Online Materials, web sites that contain vast amounts of additional data and descriptions. All of this information tends to overwhelm the reader.

Perhaps I’m just showing my age again, but I miss the days when you were limited to a strictly-enforced set number of words or pages and there were no Supplementary Online Materials. Authors had to ensure that all of the supporting facts and figures needed to tell a good story were included in the article. These requirements forced authors to carefully consider which pieces of data were the most important and to use the most concise language possible. Good papers were razor sharp and told you just what you needed to know. They were a pleasure to read.

“Just the facts, ma’am…”

On the old Dragnet TV series (I’m most definitely showing my age here!), Joe Friday used these words to cut through all the fluff and get down to the essentials. We follow the same philosophy when we write the documentation for JMP Genomics. We have divided the JMP Genomics User Guide, by theme, into nine different volumes. We describe each process in its own chapter. We tell you what the process does and what you need to run it. We then show an illustrative example and tell you how to interpret the results.

Each chapter is structured in the same way; once you learn how it works for one process, you know how it works for every process.

A colleague of mine, who documents a different software package, recently told me that the JMP Genomics documentation was rather simple. Rather than being insulted, I took her comment as the highest form of praise. Software documentation should not contain a lot of fluff. Instead, it should just tell you what you need to know in an easily accessible format and then it should get out of your way.

The JMP Genomics User Guide is designed to do just that.

Article Tags