About a year ago I took the step of pushing my old pictures and photos page to the side and starting a whimsically named blog named ‘My Programming Notebook’.
Image via Wikipedia
Exactly a year ago from this post, I published my first one: C# Base Class Call after Derived Class Block. I hadn’t quite got the concept of syntax highlighting, so I spent ages trying to colour and format it. It was interesting for me to read back on the discovery of syntax highlighting in my post Improving Your WordPress Code Display With Syntax Highlighting.
I had the ambition of publishing, on average, one post every two days, which in the end became enormously difficult to sustain. In reality, it’s about one every 2.4 days.
In the end, rather than conjure up topics to write about it, I took to writing about anything that interested me as I encountered it. Here are some highlights:
An appreciative fraction of this isn’t really programming-related (so much for “Programming Notebook”) but it has been an interesting learning experience and one I would recommend anyone interesting in improving their communication and technical writing skills.
As Joel Spolsky writes in his post about serious communication skills:
The difference between a tolerable programmer and a great programmer is not how many programming languages they know, and it’s not whether they prefer Python or Java. It’s whether they can communicate their ideas. By persuading other people, they get leverage. By writing clear comments and technical specs, they let other programmers understand their code, which means other programmers can use and work with their code instead of rewriting it. Absent this, their code is worthless.
By practicing technical writing (which can encompass blogging), and seeking feedback, so you help develop your writing style, and your language, syntax and grammar skills. Threads within your documentation can send you on research paths to broaden your understanding of the topic in hand.
Blogging, Technical Writing
Recently, I’ve experimented in breaking up the text in my blog entries with pictures vaguely relating to the content. I must confess that when looking back at them I’ve found the effect to be quite pleasing (particularly Old JamesWiseman.com).
I’ve always intended this to be a notebook for myself, but am always looking for ways to improve my technical writing, and enhance the way I convey and present information. Technical writing is an important skill for any software developer, and the manner you writeinformation is often essential to convey meaning.
For most of my career I have written technical specifications, designed to state the facts as concisely as possible, but writing blog articles like this is very different experience for me.
For a start, the tone-of-voice is different, you have to be conversational and friendly. You also have to assume that people are reading this in their own time, and not time that is being paid for by their company. This places the onus on you to make things a more interesting, and less taxing on the brain.
I did some reading up , and I quite like some of the suggestions I found on How To Write A Blog Post, which include:
Create a snappy title – Not sure that I’ve really been doing this, so I might try more after this post.- Hook your readers with a great first paragraph – Good idea. Not sure the first paragraph above is a great hook, so maybe more work required!
- Get into the nitty-gritty. Write detailed blog posts – Hmm, well, I always intended this to be a notebook so I’m maybe shirking this task. However, getting high traffic was never the motivation for this blog.
- Wrap it up. Add some sort of conclusion.
And of course, I’ll add my own – Put Some Pictures In. I tend to do a Google image search on any words vaguely relating to the topic and then put some images that catch my eye into the post.
For the record, the Google searches I did here were “Blog Posts” and “Conclusion”.
Blogging, Technical Writing
It occurred to me the other day how often I was needing to perform a ‘Paste Special’ operation to ensure the format of the pasted text was not carried across. I did a little straw-poll and found that it was most of the time.
I’d select ‘Home’ in the ribbon, drop down ‘Paste’ and select ‘Paste Special’. Latterly I found out about the ctl-alt-v shortcut, but I still found it annoying that having to do this.
So I searched around, and found exactly what I wanted on Roel van Lisdonk’s Blog. Roel assures us that this works in Microsoft Word 2010; I’ve tried it with 2007 and it also works.
We can configure Word to ignore formatting by changing some options. Start by clicking on the Office Button:
Then click the ‘Word Options’ button. When the dialog loads, click on ‘Advanced’ in the left pane:
.
The section you want is ‘Cut, copy and paste’
I changed the option ‘Pasting from other programs’ to ‘Keep Text Only’, but you are free to play around with these as you see fit.
Microsoft Word, Technical Writing
