This is the celebrated journal of Mr. Simon Collison A.K.A Colly

If I could scrunch up my screen…

26th February 2005

I need your advice again, dearest readers. I’m currently mid-way through writing my chapter for a forthcoming book about blogging. It’s the first time I’ve put together anything so lengthy to a definite publisher’s deadline, and it’s my first real attempt at combining XHTML, CSS, PHP, images and plain English in print. What’s more, I’m actually trying to make it interesting, light-hearted, and dare I say, funny.

However, I feel like I’m writing in a vacuum. Half-way through my draft, and I’m concerned about losing focus, humour, and falling into a way too rigourous formula. Well, I don’t think that’s happening, but I need to continually keep re-reading, checking my facts, and actually building what I’m suggesting.

Then, there is the way we (those of us who blog or generally write about code) incorporate code snippets into dialogue, or break large chunks into swallowable pieces for easy mastication. I keep wondering, how would other people approach this? What would make it easier, or more interesting for me as the author?

So, I think this post may be singing out to a smaller section of my readership, but all the same, if you have experience of writing about code, computers, blogs, CSS, or anything particularly technical, please let me know what works for you? How do you keep it from drying up? What do you find works as a method of breaking up a big subject into a manageable, easily followable tutorial?

Alternatively, as a reader of blogs, geeky books, or automobile-engine manuals or whatever, what format suits you? When a blogger comes up with a cracking new tip or technique, does your heart break when it’s described in a particular fashion, or is there a way certain authors write up such stuff that makes your little ticker sing?

Any advice, however vague, would be useful. Come to think of it, with a glut of new industry books being published with increasing zest, are the publishers missing out on any key subjects? Are books like “The Zen of CSS Design”, “Designing With Web Standards” and “That Book With The American Bloke In The Woolly Hat on it” (as it’s now described by all eager contracted Agenzia coders) enough, or are we putting too much focus on the exciting subjects? We all link to and talk about XHTML/CSS books, but never talk about the great books about Python, PHP or less-popular languages.

Basically, I might write a book of my own, and I’ve thought of writing about building the perfect CMS-based magazine/company/community site using a bog-standard blog tool or similar. It would focus also on managing the project, dealing with the client - sort of empowering the bedroom-based designer to take clients away from people like me. Would that be of any use to you?

Oh, I just got publishing on my mind today. Ignore, or discuss.

Responses

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

I have to say Shea’s Zen Garden book looks incredible if his preview photos are any kind of indication. As for your book, if you can keep it on-point but light-hearted you’ll pull off a big trick.

My advice? Just make sure you don’t miss anything out. If there’s one thing I despise it is following a tutorial that has a missing piece, and ending up scratching my head wondering why what I’ve done doesn’t work.

# 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.

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

The building-what-you’re-suggesting approach works well for me when I’m writing “how-to”-style stuff - so often, you realise that you’ve missed a step or two out because you fill in the gaps for yourself unconsciously. I’ve never written a whole book though…

Speaking as a reader: stylewise, Jeffrey Zeldman’s book was the best web book I’ve ever read (maybe a little too much preaching, but I guess it had to be done by someone). As well as being full of interesting examples and useful code snippets, it was also really readable, which is just so rare in a tech book. Keeping the sort of conversational, speaking-directly-to-your-readers tone of a blog works really well.

Good luck with the chapter!

# 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.

# Drew responded on 27th February 2005 with...

Oh, wait, it’s supposed to be funny too?

Dammit.

# Simon Collison responded on 27th February 2005 with...

Rachael: That’s done it - out comes my copy of DWWS, and I’v already found a couple of useful methods in there.

Jonathan: I’m with you on that. Where poss I’m trying to keep code together.

Drew: Oh yeah. Mine starts “Did you hear the one about…” and ends with “...sixteen times a night!” - it’s got Johnny Vegas in it too.

Hey, what did the barman say when Comic Sans walked into his bar?”

“Get out, we don’t want your type in ‘ere.” Ha-ha-ha-ha…urgh.

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

I liked Zeldman’s book, although I did find his style slightly annoying - too conversational. If we’re talking ‘web gurus’ here, I find Doug Bowman’s and Jeff Veen’s style of writing very easy to read.

Having written a few articles in the past and getting hopelessly tangled in introspective knots, I recently completed an article whilst constantly repeating a sentence a journalist friend of mine told me - “don’t let the words get in the way of what you’re trying to say”. Sound advice.

Keep it simple, structured and in plain English.

# 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

# Timm responded on 1st March 2005 with...

Only ever written instructions & guides for colleague education, however have found that you need to:-

1) Keep it relatively simple.

2) Assume nothing about your readers prior knowledge

3) Test instruction steps yourself

4) Get a proof reader with some knowledge of the subject in hand.

5) Test it on an end user before release.

Have to agree with the previous comments that DWWS and also Dan Cederholm’s book are written both in a very readable style and do not get lost in technical minutiae.

# Simon Collison responded on 2nd March 2005 with...

Jules and Timm: Huge thanks. Some excellent advice there, which I read just in time.

I have finished the first draft entirely. Very happy with it, aside from it being twice as long as it should be.

# Jules responded on 2nd March 2005 with...

Simon wrote: ... twice as long as it should be

Don’t worry, your editor will fix that for you, be rest assured!!!

I write this with experience. :-)

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

...Ive 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!

# Simon Collison responded on 7th March 2005 with...

Kristoffer: If it should turn into a multi-author book, I’ll get in touch for some content.

# 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.

Responses are now disabled Your ability to respond is disabled automatically some 30 days after articles are published, or manually much sooner if spamming guttersnipes target a particular article.

Prev 386 Next

Superfluous Aside

Archived in Personal, Design & Web

There are 14 responses

External References

Copyright © Mr. Simon Collison 2003-2017. Protected and licensed under a Creative Commons License. Grab the RSS feed

Engineered in Nottingham, scaffolded by ExpressionEngine, steam-pumped by United & kept alive with tea and hugs.