Human-Oriented Documentation

GitHub API is great in that it provides handy ways to deal with your GitHub resources programmatically. Its documentation is also great, which sets a good example for RESTful API designers. Let's look at one way in which GitHub API excels.

GitHub API is categorized by resources, like repositories, issues and pull requests. For each resource the API is further listed by things to do. For example, for repositories, the API  are listed as "List your repositories," "Create," etc.

Repos API

For every thing to do, it details the method and URL, parameters, input and response example.

How to create an issue

Let's look at Atlassian's Jira API.  The also list them by resources, like issues, filters and projects. Instead of using a title of just "Issue," they use a URL, like:

http://example.com:8080/jira/rest/api/2/issue

to represent issue resource. And for each resource, the API is not listed by things to do, but by available URLs.

Issues API 

Further, each URL is neither explained by what to do with the resource, but by available HTTP methods and what each method does.

POST method for an issue API

The GitHub approach is different from the Jira approach. I call the GitHub way human-oriented. When we read API documentation, we do not have in mind web resources, URL and HTTP methods first.  We solve problems. Web resources, URL and HTTP methods are about how to solve our problem, not the problem itself. GitHub API documentation starts directly from the problem and gives the solution. This is the better way.

I Love City Parks

Living in a megacity of a population of more than 20 million, very bad air and horrible traffic, I am always longing for an Arcadian life. I do not enjoy being jammed in the traffic, either underground or in the sun.

City parks are refuges for me. There are no crowds which you almost always see elsewhere. I can refrain from computers and Internet temporarily, though I confess I still occasionally tap on my smartphone for no particular reason. City parks are easily accessible. I do not have to travel much to enjoy some outer peace.

It was a bit astonishing when someone said to me, “Are you an old man? Parks are for them.” The other time when I suggest go to the nearby forest park for a stroll, I was asked “Are you a 50’s?”

They were not totally wrong when they said that. Where do people of my age like to go to? Maybe KTV’s, movies, bars, shopping malls, etc. You will surely see more senior citizens in parks than elsewhere, but there are also more children, young people especially young couples are also frequent visitors. Parks are neutral. They don’t prefer any age groups, nor they exclude any. They are microcosms of the city.

Even though I have lived in Beijing for more than ten years, I have only been to a few parks in the city. Today I went to Yuan Dynasty City Wall Relics Park. I will visit more Beijing city parks.

More on Merriam-Webster Dictionaries

I happened to see a Merriam-Webster Dictionary on my neighboring colleague's desk. I borrowed it and browsed a few pages. After some search on the web, I finally got to know the Merriam-Webster dictionaries family. I will talk about The Merriam-Webster Dictionary, The Merriam-Webster Collegiate Dictionary and The Merriam-Webster Unabridged Dictionary.

The Merriam-Webster Dictionary

Merriam-Webster Dictionary in paperback.

The paperback version turns out to be a heavily abridged one. It is the compactest one. The cover says it is based on the Collegiate Dictionary. I take the definition of the word consign here:

vb. 1 : ENTRUST, COMMIT 2 : to deliver formally 3 : to send (goods) to an agent for sale --- consignee \ˌkän-sə-ˈnē, -ˌsī-; kən-ˌsī-\   n --- consignor \ˌkän-sə-ˈnȯr-ˌ -sī-; kən-ˌsī-\  n

The definitions are to be compared with those in the other two dictionaries. On this book's Amazon page, we can see its page numbers and dimensions, which can also be compared with the other two dictionaries.

The Merriam-Webster Collegiate Dictionary

In the last post I compared Dictionary.com with Merriam-Webster.com. I prefer the former.

In fact, the free contents on M-W.com, which I think are not very complete, are from Merriam-Webster Collegiate Dictionary. They are essentially the same dictionary.

How do I know this? I signed up the 14-day free-trial of the Unabridged Dictionary, which has definitions from the Collegiate Dictionary as well as the Unabridged Dictionary. The definition in the Collegiate Dictionary are the same with the definitions from M-W.com website. Also, Wikipedia says the same thing. From its Amazon page we can see its page numbers and dimensions are bigger than Merriam-Webster Dictionary.

Definition in the Collegiate Dictionary. This is the
same with the definition from M-W.com free online dictionary.

The Merriam-Webster Unabridged Dictionary

I referred to the Unabridged Dictionary in the last post, nevertheless I did not know what on earth is this version. Now I have a 14-days free-trial of it. The definitions of the same word consign in the Unabridged Dictionary are more detailed and complemented with example sentences.

Definition in the Unabridged Dictionary.

The respective paperback version is also found on Amazon. It has more than 2000 pages and is the largest among the three.

Conclusion

It is great if you can access the Unabridged Dictionary. For free dictionaries, I still prefer Dictionary.com to M-W.com and the Merriam-Webster Collegiate Dictionary, which is the opinion in my last post.

You can go to this Wikipedia page to get more details of the Merriam-Webster dictionaries.

Compare Dictionary.com with Merriam-Webster.com

I usually use two online English dictionaries: Dictionary.com and Merriam-Webster.com. In this article I will compare them. In short, I prefer Dictionary.com over MW.

Both sites have various appealing English learning materials including videos, games and illustrations. I will only talk about word definitions and not detail on those.

Last year, I read George Orwell's novel 1984. I used MW's Android app to look up words. The good thing is that you do not need an Internet connection to look up word definitions, though listening the pronunciation does require one.

Nonetheless, I found that some words were still puzzling to me even after I looked up them up in MW dictionary. Then I opened the Android app of Dictionary.com. This app requires an Internet connection. Generally, the results are much better. Dictionary.com provides more definitions than MW, and what I really love is that it gives you the discipline on which a specific definition is.

I think MW is more like a learner's dictionary. It uses less difficult words in the definitions. On the other hand, the editors at Dictionary.com don't seem to be picking easy words: they just use what they think fit most.

I once mistakenly thought Dictionary.com used American Heritage Dictionary as its primary source. It maybe true before. Until on the first days of 2013, I found the footnote at the primary definition in Dictionary.com was 'Random House Dictionary'. I sometimes simply refers the site as AHD. I must have confused the primary source of FreeDictionary.com with Dictionary.com. FreeDictionary.com uses the definitions from AHD, and I also find them of high quality.

The other day I happened to be at the class of a teacher from the biggest English training school in China. He recommended to his GRE class Merriam-Webster dictionary. I become puzzled. MW's definitions are not complete, and I do not think they can meet the needs of the students who are preparing for GRE, one of the hardest English tests which people in China take. I asked him which MW dictionary he was exactly recommending. He told me what he referred was the unabridged version.  OK, puzzle cleared.

The gratuitous definitions we get from MW's website and its mobile apps are not from the unabridged version. To look up definitions in the unabridged version, you have to subscribe to the website: the annual fee is US $29.95 for the time I write this.

So for serious English learners, I recommend Dictionary.com over Merriam-Webster.com. If you want to use MW, since it's said that ETS uses MW as the authoritative dictionary, you really should get a copy of the unabridged version.

First Post

When I was an undergraduate student, I was at the English corner on campus. A westerner said to us, we could set up an English personal site, so that people in foreign countries could know China via this site.

I remember his words clearly. After more than eight years, today, I finally start my English blog. I could have done it the very day when I heard his words.

I will post random English notes on this blog. I don't usually set up new blogs. But when I do, I will keep posting on them.