I am also just finalizing a paper with the Supplementing part which I will try to submit in the form of a CDF file to be downloadable from the journal site. It is not a paper somehow related to programming, but just a regular paper in physics. I hope, though not sure, of course, that the journal will accept the Supplementing in this form, as it is not granted that the journal will accept the paper at all (not due to the format of the Supplementing).
Anyway, the Supplementing is prepared in a form of a CDF file. Here I list few rules I followed. The aim of these rules is to enable reading and getting maximum from my document for the reader who is unaware of Mathematica.
In order to give the reader a hint, of what he should do to read the Supplementing I included a special reference in the text. It is of the same sort as the references to cited literature in the end of the paper. This one, however, informs the reader that some material necessary for understanding he finds in the Supplementing, and that he needs to install the CDF Player to open it. I also write in this reference that the Player is freely downloadable from the Wolfram site and give the precise address of the page from where to download the CDF Player.
I start the text in Supplementing by the instruction on reading this document. In this instruction I very briefly explain what are interactive elements that the reader might meet in the document and bring examples of few of them, such as buttons of different sort that I use.
I use several interactive demonstrations, built on the basis of Manipulate, or of a comparable sort. Visually they are arranges analogously to figures. This means that the demonstration has the option Alignment->Center and below such a demonstration the reader finds a demonstration number and a text. Instead of Fig. 1 used for figures I write ID. 1 for the interactive demonstration. In the text I give a brief explanation of how to operate the demonstration in question, such as: "Move sliders to change parameters, pick up the locator (here I copy-paste the locator image) by the left mouse button" and so on. The target of all these explanations is a reader who does not use Mathematica and sees all these elements for the first time.
In fact that's all concerning simplifying reading for one unfamiliar with Mathematica. There are, however, few more hints about it.
A) The form should be CDF, rather than NB, in order to enable anyone who believes it to be necessary to download a free CDF Player and to read the paper. The .nb paper is not the option for this reason.
B) I feel that the Supplementing in the CDF form is only justified, if the interactive demonstrations are crucial for understanding the text. I would not do this otherwise, though the paper might be much more beautiful, if presented in the cdf form. However, the necessity to download and install the player may repel a lot of potential readers. If the interactive demonstrations are not really necessary, I feel that it is better to make it in the PDF form.
C) A minor thing, though useful: in such a document instead of sending the reader to some reference (such as a reference to some formula staying in another part of the document, to a literature source in the end of it, or to an image) one can bring the reference (formula, reference or image) to the reader. This strongly simplifies reading. There are several ways of doing it, but this is probably better to discuss separately. You might also wish to have a look on the discussions held in MathGroup (http://forums.wolfram.com/mathgroup/) on this subject during the last few years, especially ideas formulated by David Park there.
Just a concluding remark. We are doing such a thing among very first ones. What we will produce may accelerate a mass appearance of such type of documentation. It may also inhibit it, if we are unlucky and the documentation quality is poor. I feel that there is a certain responsibility about it.
Have fun.
