Had an idea

/

I remember ages ago listening to a radio interview with two members of Abba. They were asked how they did their song writing. They said it was a bit like being someone hunting a bear. You just had to hang around outside the cave and wait for the bear to come out. A melody might appear at any time, you just had to be ready for it. For them I think this meant sitting in the studio fiddling with this and that, waiting for the tune to turn up.

I think that writing is a bit like that too. I’ve just had quite a nice idea for an example program for the book I’m writing at the moment (gosh - that sounds pretentious - but it’s true). I’ve no clue where it came from, just I’ve spent the whole day putting down bits and bobs and this idea just popped up, mostly fully formed.

The weird, backwards nature of blog reading, where you’re reading episodes successively further into the past, means that you’ll probably see the idea before you discover where it came from, but I’m OK with that. Just remember not to stress if you can’t come up with an idea for something. Just fiddle with things around the issue for a while and, with a bit of luck, something will pop into your head...

Staying sane with missing cables

/

One trick to stay sane while writing a book is to fixate on something completely unimportant at the same time. One part of my brain is trying to explain JavaScript while another part is frantically trying to remember where I put the USB 2.0 Type A Female to USB B Male cable that I use to connect my Synthstrom Deluge to usb MIDI devices. I have absolutely no need to connect my Deluge to a MIDI keyboard at the moment, but that’s not the point. I’m getting regular exercise breaks too as I get up and look in places that the cable might be.

By mid afternoon I snapped and ordered an adapter which does the same job as the cable. Cost: two pounds fifty pence. Of course, now I’ll have to find something else to worry about.

The writing itself is going fine, which is the important thing.

How to write a technical book

/

So, I’m loitering on this forum and Tamás was asking if anyone had any tips for first time technical writers. I sent an email response and then I decided that the whole world should have the chance to read my words of wisdom…..

I’ve written a few books over the years. I can confirm that it is not a way to get rich, but at least it is a hobby that doesn’t run at a loss. I’ve self published and used a publisher. 

  • It is surprising how many typos get through when you self-publish. You have to work really hard (and show your text to loads of people) to get the same level of mistake detection as you get from a good copy editor.

  • A good technical editor adds a huge amount to a text. If you are self publishing see if you can persuade someone to take this role. Perhaps offer to pay them with a signed copy of the book. Or a nice piece of cheese.

  • Lots of pictures can make your book file large and unwieldly, but to the reader opening a book and seeing a pair of pages of dense text can be a bit demoralising. Settle for diagrams and cropped screenshots that might be less version sensitive.

  • Don’t be afraid to talk directly to the reader. When I started out I tried really hard to put things into the third person for no good reason. It’s painful and people don’t like to read it. Address the reader as “you”. Have a conversation with them. And for projects you can say “We are now.....”

  • Never say something is easy. It trivialises the point and makes the reader feel stupid if they don’t understand it. Instead tell folks how powerful the technique is and how useful it will be once they get it.

  • Context is key. Don’t tell the reader how a for loop works, tell them the situations in which a for loop would be useful, with a side order of when not to use them and how they can go wrong.

  • Readers love narrative. If you can make the text into a story or journey that will be a huge win.

  • Round things off at the end and provide a trajectory for the reader to take what you’ve told them and go further.

  • Use verbs in chapter titles – “Make a whatnot” is a quick way of setting a context. Just giving the name of a tool or technique as a heading won’t help the reader as they don’t know what it is. If you want to name the technique say “Make a whatnot with a whatsit”

  • Treat your first pass of the material as the “ore” that you you’ve mined. You then have to refine it into the finished content. Don’t be afraid of making huge changes at this point. You might have to rearrange or dump large sections until it feels right. I find that I have to “go and live” in a chapter for a week or so until I’m happy with the sequencing and content.

  • I went to a session about writing a long time ago and they talked about “Killing your favourite children”. By that they mean that you might have a chunk of text that you really like the look of, but it doesn’t really fit the context of the piece that you are writing. In that situation you need to dump the text that you love.

  • Never really throw anything away. I keep a folder called trash where I put stuff that didn’t fit (see above). Maybe it will come back as a blog post or in a different section.

  • Look at writing tools. I’m playing with something called Scrivener (https://www.literatureandlatte.com/scrivener/overview) which I quite like. It makes it very easy to organise and sequence elements (which can be given separate synopsis sections). It also has very advanced output options where the same text can be compiled to generate different output formats. I’m hoping that it will make it easy to make epubs, word documents and html pages. It’s looking promising so far...

  • Treat what you have written as collateral that you can always find an outlet for. This email is going to turn into a blog post 😊 - and it did

Cascadia Code Looks Lovely

/
cascadia.png

I’m a very old programmer. I can remember when “Courier New” was the monospaced font that everyone was using. Then came “Consolas” which I still really like.

And now we have “Cascadia Code”. I’ve decided that this typeface is one of the reasons that I like Microsoft Terminal so much. It is the default font used by that program. I think it looks really good. There’s a whole family of Cascadia fonts including some very nice “light” monospaced fonts. Well worth a look if you want to spruce up your documentation a bit.

Microsoft Word Speaks

/
wordspeaks.png

I was working on the book (did you know I was writing a book? - you can hear it here) when my fingers caught a key combination that I’d not used before. And Microsoft Word started reading the text aloud. It was kind of scary until I figured out what was going on. The reading is actually pretty good, and it is a fantastic way to proof your writing.

When I read stuff that I’ve written I find that my brain automatically edits it, adding words that I’ve missed and correcting the spelling. But if I hear it read out to me I can hear all the mistakes. You might find it useful too. You can find the Read Aloud command on the Review tool ribbon You can change the reading speed and the voice and the inflection is quite natural. It even has a good go at reading program text with variable names in it. Although it can’t say the word JSON.

Killing your favourite children

/
boats.png

Ages ago I went to a creative writing seminar. It was really interesting. One of the points that they made was that sometimes when writing you have to “kill your favourite child”. What they meant was that you might have a lovely chunk of prose that you are very proud of, but it just don’t quite fit into the context of the piece you are writing. There are two things you can do. Spend ages trying to make your wonderful words fit and fail. Or just get rid of them and move on.

I was reminded of this today when I was writing Chapter 9 of Begin to Code with JavaScript. I’m talking about software objects and I’d written a lovely piece of code that used a schema to create objects and properties on the fly. You can do this kind of thing in JavaScript and its awesome. However, I couldn’t make the example fit into the rest of the chapter. I spent far too long trying to create a solid context, wrote a few pages and then stood back from the piece, took a long hard look at it and then threw the whole thing away. What is left is much better, and of course I’ve not completely discarded the stuff. I never throw anything away.

Sometimes you have to ditch something that you really like because of your loyalty to the final result.

Useful Scrap

/
scrapfolder.png

I may have mentioned this before, but it is still true. When you start a new project, plan on how you are going to throw things away. As I write I generate stuff that is too good to throw away, but not right for where it is. I call this my “scrap”. I’ve now got a fairly structured storage for it, so that I can search for bits I wrote for chapter 2 that didn’t go anywhere, but might be perfect for chapter 4. Rule one is Never Throw Anything Away. Use GitHub to make sure that you don’t lose anything by mistake and find somewhere to put stuff that you’ve written but don’t know what to do with.

I see the first part of writing as a bit like mining. You come up with all this raw material that you then need to refine into something useful. A scrapheap to me is part of that process. So, if you start making something, build in a way of dealing with your scrap.

An expert in PLINQ for a day

/

One of the nice things about writing a book is that you become an expert on a subject (albeit in my case, just for a very short time). At the moment I know exactly how to make different parts of a Parallel Language Integrated Query (PLINQ) expression sequential so that the order of the output set is the one that you want. 

Not many people can say this.  (Oh, and PLINQ is a very neat technology by the way). 

Writing a Book

/

Back at work today. The thing that is keeping me busy over the summer is book writing. I've signed up to write a new book to teach programming. The content is loosely based on the World Famous C# Yellow book, but with a heavily practical approach. The aim is to teach people how to write programs that they could use to impress their friend. And their mum. 

The book is going to be in colour, with pictures and everything. I'll post some sample pages as soon as I can. 

C# Yellow Book 2012 Now Available

/

Yellow Pages

The latest version of the C# Yellow Book is now available for free download. You can get it here, or you can press the spiffy new short cut on this page.

There are a few changes. I’ve fixed all the mistakes that have been sent in (and probably added a few more). The section on Graphical User Interfaces now covers XAML rather than Windows Forms. And the text now mentions “The Wizard of Oz”

Harry Bosch is the man

/

image

Sometimes you just want a good book to read. Not one that has won awards, just a good narrative and some strong characters. Michael Connelly writes crime novels which are just a great way to pass the time. One of his heroes, Harry Bosch, is a hard bitten and hard boiled detective, just the kind of guy you’d want to investigate your murder (although perhaps you’d be past caring by then). Harry works the mean streets of Los Angeles and has seen a lot of life. There are a number of books which chronicle his ups and downs, you can read them in order or how you like, as each is completely free standing. If courtroom drama is more your style there are also some books staring Mickey Haller, the attorney with a heart of gold and an interesting past. All good reads.

As an exercise, while I was washing the car today I had a go at putting together a Harry Bosch style narrative. There’s actually a serious point here – from a writing point of view it is often useful to have a go at using a particular style – do a blog post from a private eye, or a president, or a poet and see how you get on. Anyhoo, with apologies to Michael Connelly, and a note that his prose is definitely not played for laughs, here’s my attempt at a Harry Bosch story:

The Axe In The Head Affair

Bosch hit the man full in the face as hard as he could. The man went straight down onto the ground, as Bosch knew he would. Bosch stood over him, waiting for the man to get up so he could hit him again. The man looked up at him, with pain in his eyes.

‘Why did you do that Harry?’ he asked

‘This is a murder investigation, not a popularity contest’ Bosch rasped, breathing heavily.

‘But I’m your partner’ the man on the ground managed to say.

‘Listen’, Bosch replied, hoping the voice of experience would get through before anything else bad happened. ‘I get through partners the way some people get through underwear. And I often leave them in pretty much the same state. The sooner you learn that, the better. Next time, remember that it is black with no sugar, not any kind of fancy coffee pourings’. His partner looked at over at the frappachino with chocolate frosting on the top resting on the hood of the squad car and nodded. ‘I just thought you might fancy a change.’ he said, getting to his feet with difficultly.

‘Now to business’ said Bosh, walking towards the other car. He could tell at once there had been a murder there. The un-natural stillness around the vehicle, the faint, lingering, smell of fresh death, and the axe sticking out of the head of the man in the driver’s seat all pointed to homicide. He paused to open his briefcase and take out a fresh pair of blue crime scene gloves from the bulk pack he carried with him everywhere. “I really must stop wearing these around the house” he thought as he put them on and carefully opened the car door.

Somebody had wanted Harvey Putz to be very dead indeed. Only a small part of the axe blade was still visible, the rest was embedded in his temple. From the angle of the blow Bosh decided that it had been wielded by a left handed female with a club foot. Or perhaps that’s what they wanted him to think, he thought grimly, remembering that this was Los Angeles, where nothing was ever as it seemed, except perhaps the weather, and even that was sometimes changeable.

‘Send the car down to the lab’ he said eventually. ‘Let’s go and see Mrs. Putz and break the bad news to her’ If she didn’t already know he thought to himself grimly.

Mrs. Putz lived in a neighbourhood of fancy cars and even fancier houses. As they drove to her address Bosch looked at the neat suburban lawns, some with children playing in the warm spring sunshine. He wondered what dark secrets each house held, and speculated on the unhappiness that undoubtedly lurked behind each brightly painted door. Mrs. Putz took her time to answer the doorbell. When she did Bosch saw that she had once been truly beautiful. Before the city of Angels did its dirty work and brought her down to its level, before her dreams were crushed and buried by time. And before she painted herself bright blue.

‘Sorry about this’ she said, in lieu of introduction. ‘Smurf convention. How can I help’.

‘I’m afraid I have some bad news’ said Bosch, ‘Your husband has just been murdered’.

‘Have I?’ boomed a male voice from behind the woman. ‘I feel fine at the moment.’

Bosch looked at the address in his notebook. ‘Is this number 82?’ he asked finally.

‘Nope’ said the man, who was also painted the same disturbing shade of blue. ‘They’re next door’.

Bosch apologised and headed back to the car, wondering if he should punch his partner in the face again.

The real Mrs. Putz was much quicker to get to the door. Almost as if she had been expecting them to call by. Bosh told her that her he had some bad news about her husband and she instantly said something that aroused his suspicions. ‘Which one?’ she asked.

That was all it took as far as the investigation was concerned. Time to move things downtown to police headquarters and transfer the conversation an interview room. Bosh used all his experience to get the suspect in the mood to talk. He left her there for half an hour to give her time to stew, gave her a cup of triple strength coffee to loosen her tongue and then turned his chair the other way round when he sat down, like he had seen in the movies.

‘So what do you think happened?’ he asked eventually, trying to get comfortable on the seat.

She wrinkled as much as much of her brow as she could. She was definitely one of the Botox generation. ‘I don’t know’ she said finally. ‘I’ve had a tragic life. My first husband died of eating poisoned mushroom soup and then my second husband died, also from eating poisoned mushroom soup.’

‘Why do you think that your third husband was hit in the head with an axe?’ Bosh asked, moving in for the kill.

‘Well’ she said thoughtfully, ‘For one thing, he wouldn’t eat his soup.’

Bosh sighed, and started on the paperwork. When would people learn that crime doesn’t pay? Unless you write good books about it.