I’ve got an 4,000 word article to finish by the end of the week. I’d much rather it was 20,000 words. It turns out that longer articles are much easier to write. You just have to churn out the words. For a shorter article, where you want to get the same points out there, you have to write the longer one first and then figure out which bits can be thrown away.
Today I wrote a section of the new book all about cookies. And then I had one with my cup of tea. Seemed somehow appropriate.
I’m presently measuring my life in chapters. I’ve just sent chapter 8 off. On to chapter 9.
I’ve shipped chapter 7 off to the publishers. And I’ve already got a big chunk of chapter 8 written because I’ve moved it around a bit. Although it might end up chapter 9 as I think about it….
I’m not sure why I buy cameras when I’m writing. But I do. They are not very expensive - so far.
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...
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.
Hot on the heels of my “why you should blog” post I discover that Simon (Darkside) Jackson has blogged (of course) a lovely pair of posts telling you how to create and host a really good looking blog site completely for free using GitHub and Jeckyl. You can find the posts starting here.
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
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.
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.
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.
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.
As I'm writing my text about C# I'm finding more and more situations where I'm saying "Leave your worries about performance until the end of development".
Now doing some stuff on string interning in C#. For some reason I have this picture of a program that gets young people in to work as strings and pays them nothing. However this is not actually how it works.....
Writing about string stuff. Needed a few lines for an example. Remembered this:
"A rocket explorer named Wright
Once travelled much faster than light.
He set out one day,
In a relative way,
And returned on the previous night."
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).
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.
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”
Spent today working on the next version of the C# Yellow Book. I’ve removed the errors that folks have reported (thanks for that, and keep them coming) and I’m updating the section on Windows Forms interfaces to cover WPF and XAML. It should be available for free download at the start of September.
Rob Miles is technology author and educator who spent many years as a lecturer in Computer Science at the University of Hull. He is also a Microsoft Developer Technologies MVP. He is into technology, teaching and photography. He is the author of the World Famous C# Yellow Book and almost as handsome as he thinks he is.
A proper developer conference in Hull. Find out more here.
