Archive for the 'Technical writing' Category

Why open source software (FOSS) struggles for acceptance

I like open source stuff, for a variety of reasons. I like the philosophy behind it, and I like the idea of many eyes and many hands working together to create better things. While I do understand that there are situations where open source is not appropriate, such as with the proprietary things I work on in my day job, I also believe that there are many cases where open source is not only appropriate, but necessary.

Software is a case in point for open source. With open source software there is less likelihood that someone will slip a nefarious backdoor into an application, and the overall “attack surface” (as the security folks call it) is much smaller than with closed applications. Free open-source software (FOSS) also has the benefit of multiple eyes reviewing it, finding bugs, suggesting (or creating) improvements, and serving as inspiration for other projects. But there are two problems with open-source software that I believe will be fatal in the long run: The documentation sucks, and the attitude of some of the people who write FOSS does nothing to help the cause. I believe that these two things are closely related.

Continue reading ‘Why open source software (FOSS) struggles for acceptance’

Fun with book titles

Well, it seems that there is a problem with my latest book. Turns out that someone in Europe decided to create an e-book and name it “Arduino In a Nutshell”. Well, OK, but that’s not cool, because O’Reilly has been using the “Nutshell” titles for many years. It even states in the front of the Nutshell books that the Nutshell theme is a registered trademark (but IANAL). I’m a bit irked by all this, as you may well imagine.

But rather than pick a fight and piss off the Arduino community, which neither I or O’Reilly really want to do, my book will get a new title. And the copyright registration will have to change, and the ISBN number will probably have to change, and so on.

The current front-runner in the title race is “Arduino: A Technical Reference”, with some form of clever subtitle to go along with it (subtitles are all the rage these days, it would seem). I originally wanted to call it “The Arduino Technical Reference” because after all, that is what it is. I write technical references and textbooks, I don’t do “99 Amazing Projects” books (complex projects are hard to do and document well in a short time frame, simple projects are easy–I suspect that’s why there are a lot of the amazing simple projects books). But technical authors don’t often get to name their own books when publishing through mass-market outlets, mainly due to marketing concerns and editorial whims.

If you have downloaded an early release version of the book, safeguard it. That is the last and only release that will have the original title. Congratulations, you now own a collector’s item.

I’m hoping it just all slides quietly under the bridge. I guess I’ll just have to wait and see.


UPDATE 9 April 2016

My latest book is now officially called “Arduino: A Technical Reference” with some additional sub-title stuff (O’Reilly seems to really like sub-titles). It’s available now for pre-order on Amazon and of course from O’Reilly directly.

From the frying pan into the fire

Update: The book is now called “Arduino: A Technical Reference”. See post above for details on the name change.

My latest book, “Arduino In a Nutshell” has finally gone into production. Whew, it took almost a year to write, and it’s probably a tie with “Practical Electronics” for the amount of artwork and photos. I sometimes wonder if I’m actually writing graphic stories for nerds like myself.

It won’t be on the shelves in the bookstores for about another month or so, depending on how much production wrestling is required. But in the meantime you can get the “Early Release”, which is O’Reilly’s way of drumming up interest before they actually light up the printing presses.

The title, by the way, was O’Reilly’s idea, not mine. I wanted to call it “The Arduino Technical Reference” because that is what it really is. But, O’Reilly has been publishing the nutshell series of books for over 20 years, and I guess they want to stick with it.


Failure to communicate

I know I should get over it, but I never cease to be amused/dismayed by the people who make comments about a book that don’t even relate to the book in question. Case in point: Someone commented that my recent book from O’Reilly, Practical Electronics: Components and Techniques, didn’t have the information that they wanted regarding “…an example of how to interface a simple serial circuit with a USB port and read data…”

Continue reading ‘Failure to communicate’

Follow Crankycode on

Little Buddy

An awesome little friend

Jordi the Sheltie passed away in 2008 at the ripe old age of 14. He was the most awesome dog I've ever known.