Generally speaking, you should spellcheck everything you write. Word has some fairly decent in-built spelling and grammar checking, and while it may not get everything, it’ll catch a lot. However, on occasion, there’s content you really don’t want to spellcheck. Case in point: API/developer documentation rife with code samples: yes, I did mean to spell it that way; yes, it is all one word; no, I don’t want to capitalise that just because it’s at the start of a line; no, I don’t want a space after that semi-colon… And by the time you’ve hit Ignore for the umpteenth time in a row, you realise you’re back in body text, and you’re not sure how long you’ve been on auto-pilot clicking Ignore, and who knows what garbage you’ve said is ok to leave as is now, and you may as well go right back to page 1 and start over. So what do you do? Forego spellchecking entirely? Copy and paste the non-code-sample bits to a separate doc, spellcheck, then merge back in? Or magically tag the code samples as not to be spellchecked and live happily ever after? It’s a leading question, I admit it. The last option it is, and today’s post is on how to do just that! Continue reading “Do not spellcheck!”
Tag: Programming
What does API documentation look like?
How long is a piece of string? If you’re starting a new API documentation project and want to see examples of how other people have tackled presenting the information, head on over to http://www.programmableweb.com/ which catalogs a plethora of public-domain API docs in its directory, as well as providing API-related news articles, and some useful how tos.
What’s an API?
I really like this crash course from Zapier that explains what a REST API is and how it works. Each lesson is short and well laid out, with good visuals, and interactive exercises. A great resource for a beginner, or someone in need of a quick refresher! 🙂
Book Review: Learn to Program with Scratch by Majed Marji; No Starch Press
My latest selection for review from the O’Reilly Review Program is Learn to Program with Scratch by Majed Marji.
I picked this because my eldest has started to mess around with Scratch and I didn’t really know anything about it myself, so I wanted to get up to speed to be able to answer his questions.
The introduction says the book is targetted at readers from middle school and up: Wikipedia tells me that in the US this is age 11/12. It would definitely be beyond my 8yo to read this himself, and despite the kid-friendly looking cover, I found it challenging myself in places, despite being no spring chicken! 🙂
Things I liked:
- As promised on the cover, it’s visual. There are lots of illustrations to help you identify GUI elements and to get an idea of what you’re aiming to achieve through the use of certain functions and tools.
- It includes lots of short examples – “if you use these blocks, then this will happen, for example…”.
- It includes “Try it out” sections suggesting how you might tweak the current task/project to get a different result, giving scope to experiment and learn more.
- There are problems at the end of each chapter, so you can check you’ve really absorbed and undestood what was covered.
- Lots of example files are available to download, so you can save yourself some work on initial setup and get straight to the trying things out if you prefer.
Things I didn’t like:
- I found the longer examples/projects difficult to follow at times – possibly because they were mainly described in a series of paragraphs, rather than neat numbered steps or highlighted bullet points. This may be entirely down to my personal learning style, though, so your mileage may vary. It’s also possible that since I worked from the ebook edition rather than print, any formatting restraints imposed by that medium may have affected readability.
- Sometimes, you’re told which palette certain blocks come from, other times you aren’t. I guess it’s a “first mention” thing, but since a number of the palettes are similarly coloured, and my memory isn’t what it once was, I could’ve done with a bit more help in the later examples.
- I wasn’t keen on labelled images where you had to follow the trail from (1) to (2) to (3) to understand what was happening. Again, this one can probably be put down to learning style preferences.
There is useful information in there, but I think I’d’ve been happier using this book as a reference/refresher or source of ideas if I’d already learned the basics elsewhere – I didn’t find it ideal as my introduction to Scratch.
You can find out more about the book and order it direct from O’Reilly here.