Tag Archives: reference

Recommended open source docs

Programming books and documentation on shelfHaving written a fair bit of technical documentation, this tweet requesting recommendations for the best open source docs caught my eye:

Thankfully lots of people were keen to suggest good examples and six hours later I went through the replies. The variety was surprising, from man pages to tutorials to core modules so well written you “don’t really need documentation to understand it”! In the end, there were a few that got several mentions so for the record, here are the open source docs that were recommended at least twice, with one clear winner:

Photo by Niels Heidenreich: https://www.flickr.com/photos/schoschie/1330790063/

How the Japanese communicate, part 1: Alphabet

This is the first of a few articles introducing the way Japanese people communicate with each other. They won’t teach you how to read, write or speak Japanese but they should hopefully be enlightening for people with no previous knowledge. Let’s kick off by looking at the alphabets (yes, plural) that Japanese people use.

Just a bunch of squiggles

Sumo flagsThe thing that attracted me to Japanese was not manga, anime or robots like many others. It was sumo wrestling and squiggles. On first sight, Japanese looked liked random squiggles but the thought of being able to glance at it and actually know what’s written seemed so cool. I’d be like a spy cracking a secret code! Even now, many years later, I still get a thrill from seeing a bunch of squiggles and understanding (most of) it.

Characters all the way down

It’s commonly said that Japanese has thousands of characters. Yep. But that’s only in one alphabet. There are two further alphabets with much fewer characters. Here’s how they break down:

Alphabet name No. of characters Style Example: kuruma (car)
Hiragana 48 curvy くるま
Katakana 48 angular クルマ
Kanji Up to 50,000 but 2,000-3,000 used daily fancy

Let’s look at these one by one.


Hiragana charactersJapan is still a pretty sexist country but 1,300 years ago it was much worse. Women were only allowed a lower level of education than men so consequently didn’t use the thousands of Chinese characters (kanji) that men did. Instead, they started using a cursive, simplified form of a handful of kanji to represent sounds and ignored their meaning. For instance, to write kumo (cloud), they could have used derivations of 久 (long time) and 毛 (hair, fur) which, over time, became the hiragana く (ku) and も (mo). This spread from ladies of the imperial court so that eventually men also used hiragana for unofficial writing. It’s now the foundation for reading and writing in modern Japan so if you only learn one Japanese alphabet, make it hiragana.


Collectively known as kana, hiragana and katakana are phonetic alphabets and it’s no coincidence that they both have exactly the same number of characters (48) — they each have the same pronunciation and sometimes even look similar. For example the hiragana か (ka) is ヵ (ka) in katakana. This can be confusing but katakana are easy to spot because they look very angular whereas hiragana have curves. But why have two similar alphabets at all? Good question. Katakana developed at about the same time as hiragana but are now used when writing foreign words primarily from Western cultures, such as ロケット (roh-ke-tto) for rocket. They are also used for onomatopoeia and for adding emphasis or a “cool” factor. For example, the word for fashionable is オシャレ (o-sha-re) which, despite being an originally Japanese word, is often written in katakana to seem, well, fashionable.


The two characters for the word kanji (漢字) mean “Chinese character” and that is indeed where they came from. Korean also uses various Chinese characters but because of a decree by Mao Zedong in the 1950s to simplify characters to improve literacy in China, modern Chinese characters (except in places such as Taiwan and Hong Kong) can be quite different to those found in Korean and Japanese.

Pronunciation is also a little complex. Some kanji retain their sound from Chinese, e.g. three (三) is pronounced san both in Mandarin Chinese and Japanese. Some have evolved slightly over the centuries, e.g. famous (有名) is you-ming in Mandarin Chinese and yuu-mei in Japanese. In other cases there seems to be no similarity. And as if that’s not enough, each kanji has at least two correct ways of pronouncing it in Japanese. More about that in a later article.

But despite these challenges and having thousands of them to learn, for me, kanji are the most beautiful aspect of the Japanese language both in their form and their logic. They range from very simple to very complex and can be works of art in themselves. Some are figurative, for example the character for tree (木) looks sort of like a tree, and some are clearly abstract. Characters can be combined to make a more complex character and can be chained together, most commonly in pairs, to make words. Let’s see a quick example of this.

  • The kanji for sun is 日 (pronounced hi, ka, nichi or ni).
  • We’ve already met the kanji for tree (木) but if we add a small line at the bottom to make 本 it now means root or origin (or book, incidentally).
  • If we chain these two kanji together we get 日本 (ni-hon) meaning origin of the sun, or land of the rising sun, i.e. Japan.
  • Adding the delightfully simple kanji for person (人) to the end gives us 日本人 (ni-hon-jin), meaning Japanese person.

Isn’t that beautiful?


Is there an “alphabetical order” for hiragana and katakana?
Yes. The hiragana/katakana order sounds like this: a i u e o, ka ki ku ke ko, sa shi su se so, etc. Notice a pattern?
Is there an “alphabetical order” for kanji?
Not really. They can be ordered by their number of strokes (how many lines each one has) and there’s also a fixed order that children learn them in at school.
Speaking of which, at what age do children learn the alphabets?
Hiragana and katakana are learnt first at around age five or six. Children then spend several years learning the kanji — 1,006 in elementary school and another 1,130 in junior high and high school.
How do children learn them all? Are they geniuses?
Hah, they wish! They have to sit and memorise and test and moan just like kids all over the world.
Is there an ABC song equivalent?
Unfortunately not. Feel free to write one.


Photo of sumo flags by David Steadman: flickr.com/photos/90949166@N00/4274125768/
Photo of hiragana by Antonio González Tajuelo: flickr.com/photos/antoniotajuelo/4782563135

Incandescent bulbs and lumens

An incandescent bulb switched onI’ve been buying LED bulbs but am surprised at their brightness, or rather lack of. Manufacturers often write the equivalent in watts of incandescent bulbs on the packet but it turns out they tend to, er, lie. Quite a lot. With the current boom in LED bulbs, a trustworthy comparison table is what’s needed.

After a bit of searching, I found this helpful article published by the European Union:
Energy-saving lightbulbs – how to read the packaging

They confirm that measuring brightness in watts is now pretty much meaningless so instead, here are the lumen values you should look for when replacing your incandescent bulbs:

Incandescent bulb Lumens
25W 220-250
40W 410-470
60W 700-810
75W 920-1060
100W 1300-1530

Photo by Teodoro S Gruhl

Free online web development checkers

A green checkmark

Inspired by a forum post I came across the other day I’ve compiled a list of free online checkers/validators for web developers. Please let me know if you’re aware of others. (Updated 16th September 2010)