If I could scrunch up my screen…

# shawn responded on 26th February 2005 with...

Just like anything else, plan it out. You’ll have a much easier time reaching your end goal if you have a clear vision of the way to get there.

# Jonathan M. Hollin responded on 26th February 2005 with...

As a programmer, I am constantly reading books and other documentation where large blocks of code are presented and discussed. I’ve always found the most useful presentation is a simple, unbroken code-listing, with line numbers. This is then followed by a breakdown that refers to specific lines, or blocks. For example:

Lines 1-10: Initialisation and variable definitions
Line 14: Reset the woggle widget
Lines 18-30: Woggle control loop

This works for two distinct “views”. 1) I can see the code in-situ, this is often useful to be able to quickly understand the overall mechanics and 2) I get a detailed description explaining the finer points - with line-numbers as index points.

Personally I am always more comfortable with code presented this way.

# Jules responded on 28th February 2005 with...

I picked up three techniques during my writing (the list is missing one book) and they are:

1. sidebars,
2. headings, and
3. chunking

Sidebars

My publisher’s book style used three types of sidebars. The “pencil” sidebar was used to indicate additional information such as the currently available browsers. This type of information was extraneous to the main topic — I tried to ensure that these sidebar topics were related to the current topic but not essential to the lesson being taught. Another sidebar type was the “bomb” which was a type of sidebar indicating a potential problem and how to solve it. The third type of sidebar was a “windows” sidebar which was to indicate where there were differences between the Windows and Mac versions of Dreamweaver. While the specifics of these sidebars may not be applicable to your book, your publisher may provide you with some latitude to create at least one type of sidebar, if not more. I found these were very useful to add additional information that was useful but not critical: it allowed me to add useful information yet separate it from the critical information. Unlike the sidebars in Joe Clark’s book, which are just pull-quotes, my sidebars were longer and more substantial (though not necessarily more important than Joe’s by virtue of their length). BTW, the sidebars did use pencil, bomb, and Windows icons to indicate the type of information presented in each with a legend at the beginning of the book.

Headings

I found it very useful to make use of headings to break up topics. It allowed me to keep focus on the material at hand and, hopefully, keep the reader focused. Although my publisher allowed only 2 heading levels, in the end, it was sufficient.

<styleguide.com/”>Web Style Guide, 2nd Ed.<styleguide.com/site/chunk.html”>basic principle for the lessons in my books. My publisher required that the exercises consist of no more than 12 steps per exercise although there may be more than one exercise in a lesson. Like headings, this forced me to break down a topic or lesson into more manageable — and more focused — exercises. For example, the lesson may be to style the H1 selector so exercise 1 may be to create an empty .css file and exercise 2 may be to create the selector and style. In the final project of the last book, there were close to 15 exercises with anywhere from 5 to 10 steps to each.

As I have mentioned before, your publisher may not have the same “restrictions” I had. If you have some flexibility, you might want to consider some of these ideas.

Best of luck,

Jules

# Kristoffer responded on 7th March 2005 with...

...IÃve thought of writing about building the perfect CMS-based magazine/company/community site using a bog-standard blog tool or similar…

Go ahead! I would buy that book right away!

# Rob Waring responded on 10th March 2005 with...

Pictures! A lot of the books I’ve read (mostly programming ones) bung pics of what the end result of the code should be in to start with an then lose them by the end of the book, occasionally the second chapter. Lots of nice clear photos showing what should happen when you do x, y, z, is always good for when people aren’t reading the book in front of a computer and so can’t try it for themselves.