Saturday, March 21, 2015

Nimbicus: An original game to play on a children's bead abacus stacker

You can play a surprisingly good variant of a nim game on this bead abacus stacker that I found at a friend's house on Friday night. I call this game Nimbicus.

Here are the rules I devised on the spot [1]: The frame contains 5 pegs of different height, each of which takes, 1, 2, 3, 4, or 5 balls. There are 15 balls in five colors, with 1, 2, 3, 4, or 5 balls in each color. The game starts with all of the balls off of the frame.

On your turn you must do ONE of the following: 1) Take as many balls as you like that are all the same color and put them all onto a single peg, or 2) Take exactly two balls of different colors and place them onto two different pegs.

The peg(s) must have room to accommodate the balls you selected. The peg(s) on which you place the balls can have other balls on it from any colors; you don't have to match the ball colors already on those pegs. When choosing the first option, you can take any number of balls you want of the same color; for instance, if there are four yellow balls, you can take 1, 2, 3, or all 4, as long as there is space on a a single peg to place them.

As in other nim games, the last player to play loses.

Analysis

There are only 15 balls, which makes this a very limited game. What complicates this is the varying color choices and limitations imposed by the spaces on the pegs.

Let's refer to the available balls at the start as (5,4,3,2,1) and the available frame spaces as [5,4,3,2,1]. As options disappear, we can ignore ball colors and spaces that have no available choices. So, for example, if there are three balls remaining in 2 colors, you can select (1), (2), or (1,1), but only if the frame spaces allow for these selections. If the remaining frame space is [3], you can't select (1,1). If the remaining frame space is [1,1,1], you can't select (2).

First Moves

For your first move, you have 25 choices for selection: 1 ball from (1), 1 ball from (2), 2 balls from (2), 1 ball from (3), etc up to 5 balls from (5): that's 15. You have 10 more choices for (1,1) from the 5 available colors. That's the selection.

Now you have to place the balls. If you chose (1)  (5 different possibilities), you have 5 choices for placing. That's 25 possibilities.
(2) (4 choices) x 4 placement possibilities = 16
(3) (3 choices) x 3 placements = 9
(4) (2 choices) x 2 placements = 4
(5) (1 choice) x 1 placement = 1
(1,1) (10 choices) x 10 placements = 100

Add it all together and you get a total of 155 options for your first move.

End Games

Let's work backwards, instead.

1 ball

You lose if it is your turn and there is one ball.

2 balls

You win if it is your turn and there are two balls. Place one on the frame, and now your opponent has 1 ball.

3 balls

There are nine options for 3 balls. In some configurations you can force a win, and in others you have lost.

StateBallsFrameWin/LossComments
3.1(3)[3]WinPlace (2), leaving your opponent with one ball.
3.2(3)[2,1]WinPlace (2), leaving your opponent with one ball.
3.3(3)[1,1,1]LossYou must place (1), leaving your opponent with two balls.
3.4(2,1)[3]WinPlace (2), leaving your opponent with one ball.
3.5(2,1)[2,1]WinPlace (2) or (1,1), leaving your opponent with one ball.
3.6(2,1)[1,1,1]WinPlace (1,1), leaving your opponent with one ball.
3.7(1,1,1)[3]LossYou must place (1), leaving your opponent with two balls.
3.8(1,1,1)[2,1]WinPlace (1,1), leaving your opponent with one ball.
3.9(1,1,1)[1,1,1]WinPlace (1,1), leaving your opponent with one ball.

4 balls

There are twenty five options for 4 balls. In some configurations you can force a win, and in others you have lost.


StateBallsFrameWin/LossComments
4.1(4)[4]WinPlace (3), leaving your opponent with one ball.
4.2(4)[3,1]WinPlace (3), leaving your opponent with one ball.
4.3(4)[2,2]LossIf you place (2), you leave your opponent with two balls. If you place (1), your opponent is left in state 3.5.
4.4(4)[2,1,1]WinPlace (1) in the [2], leaving your opponent in state 3.3.
4.5(4)[1,1,1,1]WinPlace (1), leaving your opponent in state 3.3.
4.6(3,1)[4]WinPlace (3), leaving your opponent with one ball.
4.7(3,1)[3,1]WinPlace (3), leaving your opponent with one ball.
4.8(3,1)[2,2]LossIf you place (2) or (1,1), you leave your opponent with two balls. If you place (1), your opponent is left either in state 3.2 or 3.5.
4.9(3,1)[2,1,1]WinPlace the single ball in [2], leaving your opponent in state 3.7.
4.10(3,1)[1,1,1,1]WinPlace the single ball, leaving your opponent in state 3.7.
4.11(2,2)[4]LossIf you place (1) or (2), your opponent places (2) or (1) respectively.
4.12(2,2)[3,1]LossIf you place (1), your opponent places (2). If you place (2) or (1,1), your opponent is left with two balls.
4.13(2,2)[2,2]LossIf you place (1), your opponent places (2). If you place (2) or (1,1), your opponent is left with two balls.
4.14(2,2)[2,1,1]LossIf you place (1), your opponent places (1,1) or (2). If you place (2) or (1,1), your opponent is left with 2 balls.
4.15(2,2)[1,1,1,1]LossIf you place (1), your opponent places (1,1). If you place (1,1), your opponent is left with 2 balls.
4.16(2,1,1)[4]WinPlace (1) from the (2), leaving your opponent in state 3.7.
4.17(2,1,1)[3,1]WinPlace (1) from the (2) in the [1], leaving your opponent in state 3.7.
4.18(2,1,1)[2,2]LossIf you place (2) or (1,1), you leave your opponent with two balls. If you place (1), your opponent is left in state 3.5 or 3.8.
4.19(2,1,1)[2,1,1]LossIf you place (1), your opponent places (1,1). If you place (2) or (1,1), you leave your opponent with two balls.
4.20(2,1,1)[1,1,1,1]LossIf you place (1), your opponent places (1,1). If you place (1,1), you leave your opponent with two balls.
4.21(1,1,1,1)[4]WinPlace (1), leaving your opponent in state 3.7.
4.22(1,1,1,1)[3,1]WinPlace (1) in the single spot, leaving your opponent in state 3.7.
4.23(1,1,1,1)[2,2]LossIf you place (1), your opponent places (1,1). If you place (2) or (1,1), you leave your opponent with two balls.
4.24(1,1,1,1)[2,1,1]LossIf you place (1), your opponent places (1,1). If you place (2) or (1,1), you leave your opponent with two balls.
4.25(1,1,1,1)[1,1,1,1]LossIf you place (1) or (1,1), your opponent places (1,1) or (1) respectively.

Note that you always lose if the frame configuration is [2,2] on your turn, and you always lose if you're left with (2,2) on your turn.

5 balls and more

There are 49 options for 5 balls. Things continue to grow, but slower, for more balls, since limitations on spaces and ball colors begin to apply. The whole thing is not terribly hard to work out with a computer, but it doesn't appear to be easy to figure out for humans, unless someone hands you the winning strategy.

Variants

I created the game after showing my daughter the Towers of Hanoi puzzle on this. It's not hard to add a number of twists to the game to change the challenge. For example, you could say that certain colors are not allowed to be placed next to or on top of (like Towers of Hanoi) other colors.

Yehuda


[1] I vaguely recall rules similar to these in other games I have played, so the idea isn't original, although I think the game is.

Tuesday, March 17, 2015

20 API Design Tips to Stop Annoying Developers

Here is my presentation at DevConTLV March 2015, slide by slide, with my accompanying talk and some notes. I don't write down what I say on the slides, not do I have a script, so the text is an approximation.

This talk was supposed to be 20 tips to stop annoying developers, but I stopped counting at 20. You're welcome to count along with the presentation and tell me how many there are at the end.

Every example in this presentation represents an actual example I've seen while documenting APIs.

Just to clarify, the title of this presentation means tips to "stop doing things that annoy developers", not "stop developers who are annoying". Which brings me to my first tip ...


Don't name your APIs with names that have ambiguous meanings. English can be tricky; if you're not a native English speaker, get one to help you review your function and parameters names.

What's confusing here? "Barks" can mean "This animal can bark" or "This animal just barked". If a developer sees this, he or she can't tell which one you mean just by looking at it. Try one of the following.

Now the action can't be misunderstood. However, ambiguity is just the start.

Take a look at the first one, "can_bark". This turned out to be a problem for me when I was documenting an API.

Typically, there are two types of APIs. In the first type, all of the business logic is in the API. In this case, the application acts as a funnel, sending information to the API and passing requests from the API back out. The application is notified about things that happened on the server, or by the user, or on the device, or in another application, or even another part of the application, and sends the information to the API. In turn, the API sends things back to the application and the application sends it back back out to the world. For this type of API, the application isn't supposed to think.

My documentation was supposed to say when to call each API function, and what to do with the information sent back from the API. The developers included a sample application that had this API "can_bark" in it. I asked the developers "When does the application call this?" They said "When the API is waiting for it". But when is that? Just look in the sample application. That's not the point, I said. The application isn't supposed to have business logic in it. The application can't know when to call anything; it just responds to external requests. If it has to decide on its own, I need to write a whole new document on how to design the application's business logic.

Essentially, the developers had drifted part of the business logic to the application, instead of keeping it in the API where it belonged. As a result, you had an API that could not be called, let alone documented, because it didn't have access to information that was inside the API.

This API would have been fine if it responded to an event or call of some kind from the API itself. In other words, it didn't have to think for itself if it just responded to a request from an external source (the API) as usual, sending the requested information back to the external source.

(Another situation arose when new information arrived about an animal ("this dog can bark") to be sent to the API. The information could be sent using an API that already existed "animalUpdate", which meant that the new API wasn't required.)

The moral of the story is: don't split your business logic. If you use the kind of API that has all the business logic, keep the business logic in the API.

Another kind of API has none of the business logic and simply responds to requests from the application. For example, a device driver writes what the application tells it to write and reads what the application tells it to read. If you drift application business logic into this API, your next customer is going to want something different from it and you're going to have to redesign the API.  So don't split your business logic.

This is me. I worked for 14 years as a system administrator and a web programmer, until I switched to technical writing over ten years ago. Between my roles as technical writer, teacher of game rules, and now a designer of APIs, one of my major skills is to turn complicated ideas or topics into very simple ones. I teach complicated games so that they can be understood in only a few minutes, take 200 page documents and turn them into 120 page documents, and take 60 page documents and turn them into 2 page tech sheets.

I have documented dozens of APIs. When I get an API to document that is overly complicated, or would require a lot of documentation (and therefore a lot of work for the integrator to understand) because it doesn't match the rest of the APIs, I go back to the developers and say, hey, rather than write complicated documentation, let's rewrite the API. That gets me into trouble with some developers, but the product managers are generally happy. The result, in some of the places that I worked, was that API functions, names, parameters, and so on went through me before they were implemented. I sat in the design process.

Which makes sense. It's not enough for a web site to work. Nowadays you hire a UX designer to ensure that your web interfaces are clean and neat and don't drive away potential users. The same should be true for your APIs. It's not enough to say "they work!" If they are complicated, ugly, or difficult to integrate, you may drive away potential integrators.

In this talk I'm first going to talk about what makes a good API in general. Then I'll give some general tips for APIs, then some specific tips for specific instances, like actions and parameters. I'll end with general tips about documentation and delivery.

What is the object of an API?

It's the same object as your UI or your product: help your customers to be awesome.  (Note that I stole this idea from a fantastic lady and speaker, Kathy Sierra.) The ultimate object is not to have an awesome product. Your product should be awesome, of course, and you can sell that in your marketing documentation. But no one wants to use your API, or read your document, or even use your product (unless it's a status symbol). They use it because they have to in order to be awesome, to do what they really want to do.

People buy a cool bicycle because it has a tungsten carbide frame, cool anti-rust paint, blah blah. But then they have to use the bike - interface with it - and they don't want to spend time trying figure out your fancy features, If the interface isn't "get on the bike and push the pedals", it means that they have to read the manual.

"Have to" is not a Good Thing. People "have to" use your APIs or "have to" read your documentation. No one "wants to" do these things (unless you're a hacker who loves systems, like me), so it's a negative experience. They do them because they have to. If they can do it easier using someone else's product, they will. If they have to use yours because you have a monopoly on some kind of feature, they will; you have them over a barrel. But you're not going to make any friends by forcing someone to do something that they "have to" do.

The object of any API is the same as the object of a technical document: to have the user/reader use it as little as possible. Ideally, not at all. If they have to use it, You've already lost something. Make it as simple, quick, and painless as possible for the user to get in and get out.

Your job in writing an API is not to sell your technology. You should not write an API that goes "start the super cool dog grooming feature". The API should be "groom the dog". Keep focus on what the user wants to do, not on what a great feature you're providing. Otherwise, your API will be bloated and loaded with all kinds of things that you think are cool but are forcing users to learn your language, showing off features that are not helping them get in and out as fast as possible. Obviously, if a user has to use a feature, you have to provide a way for him or her to use it. But keep the focus on the user, not the technology.

(Here's another slide totally stolen from Kathy Sierra.) On the left is what you promise your customer. She's going to take a cool picture while climbing a mountain. It's going to be awesome. On the right is what you deliver to the customer: technological documentation and interfaces in love with themselves, all of which she has to wade through to get to the cool picture on the left. Again, some of this is inevitable; you have to describe how the camera really works. But keep the gap as small as possible. Focus on getting the user in and out of your API as fast as possible so they can get to being cool.

 So what makes a good API?

A good API (or document) is invisible. The customer doesn't feel it or see it any more than they have to. It is so natural that it doesn't feel like they are learning or using it.

A good API (or document) is unsurprising. If there's a left, there's a right. If there's an up there's a down. If it works one way here it works the same way there. It works the way every other API works. The user doesn't have to know something different to use every functions. It works exactly as expected, so that it needs no (or almost no) documentation.

An API that presents a few good features well, unsurprising, and easy to implement is better than one with lots of complicated features that have to be learned one at a time. Complicated, hard to understand and hard to implement. It may be inevitable that you have to provide something bad or complicated for a feature that the user MUST use, but minimize this as much as possible.

In the end, an API is good when the user feels that the money he or she spent on the product was worth it.

Have someone constantly looking it over to ensure that it's all consistent and logical, even if you are working in agile. Agile development adds features here and there as they come up without worrying about how they fit together as a whole. Ronit on Inbal's team added this feature, and Itzik on Moshe's team added that feature, and they all work, so done, right? No. Ronit used one kind of parameter set and Itzik used a different kind, and now the integrator has to learn two different methodologies to integrate them, which is annoying.

Keep a master plan for your actions, objects, parameters, and values, and keep it up to date with each new addition and each release.

Because it's very hard to change an API after it's released. If your code has mistakes and discrepancies that are hidden from the user inside the code, I don't care. You can release new code and fix it. When an API is released and customers are using it, it's painful and annoying to have to rewire an applications to incorporate the new API. It's worthwhile getting the API right the first time.

How do you write a good API? Think like a customer. A customer thinks: what do I want to do? Give the customer use-cases that show what your API does, and give him APIs that do things, with useful verbs.

An R&D team has access to all kinds of dummy information at all times. They forget that, in the real world, the integrator starts with nothing. If your API takes the list of dog breeds as input, where does the customer get that list of breeds? From this other API, that requires the list of dogs. Where do they get the list of dogs? From this other API that requires the list of kennels ... It's ok to cascade API requests, just make sure the developer can easily find the input for every API.


Then make sure they can use the results you send back to them as the input for the next API. Don't send back dog names in one API and ask them for dog IDs in the next. Unless the returned information is heading straight to a UI screen or a log file, your user is not a person, it's an application; it needs to feed the results of one request into the next.

How do you end up with this, where one function is camel case and one has underscores? Well, Ronit on Inbal's team added one feature, and Itzik on Moshe's team added the other feature. "It works!" But it's annoying. Don't do it.

Same thing for the parameter order and what gets passed. The first function takes a pointer, the second takes the variable followed by a Boolean, and the third takes the Boolean followed by a literal. How did this happen? Ronit on Inbal's team added the first one and ...

Here dogs are defined by a flat set of fields with feet and so on. But cows has a two-level structure of fields with limbs, followed by feet and hands. Be consistent in how you construct your data structures.

If a name or a term appears somewhere it should mean the same thing everywhere, and the terms you use for one thing should be the same for everything. Your pet store started with only dogs, and the names used "name". They added cats, and now they use "catName". Please. Also, "bark" means one thing, for dogs yes or no, but "bark" is the same word but has a different meaning, an enumeration, when used for trees. Be consistent.

Shorter is nearly always better. Shorter words are clearer and more logical. I know you want to be helpful by adding "is" and phrases and so on like this, but it's more to read for the user and not any more clear. In this case, the test "is this an animal" is always going to appear in an "if" clause, and it reads cleaner by just using the noun "animal", which means yes or no.

But there is a limit to being short. Don't abbreviate English words. Aside from being hard to read, you might run into abbreviations that can mean more than one word. I keep running into abbreviations or acronyms used by non-native English speakers that have unintentional vulgar or ridiculous meanings.

Here the type is "dog" but the user still has to define all of these other things, like the number of "legs" and the sound a dog makes, when these should be defaults. Use defaults.

Your company decided to rebrand. From now on dogs will be "BarkBuddies". That's fine, and the new APIs use BarkBuddies, but all the old ones still use dog. Don't do that. Yes, it's a pain to have your customers move to a brand new version of the API, but that's still better than an API that uses several types of terminology for the same thing. It starts with just a few functions but it always ends up as a mess.

Get someone to review your function names, parameter names, and so on BEFORE you implement them, not a week before delivery when your R&D team is too busy to revamp all of the code to fix problems. Because they won't. They'll say they'll fix it in the next release, but by then it will be too hard and too late, and they'll be working on new features.

In my jobs, new functions went through technical writing, but it could just as easily go through QA or support, as long as it goes through someone who writes English well and will push back and ask for changes.

And of course, make sure it really does work. An API with functions that don't actually work is annoying, too.

 Here are some more specific tips.

Use a consistent naming structure for your actions. For instance, if you add a new animal, always use "add". Or "create" or "set", whatever you choose, just always make it the same. One popular method is "CRUD" which stands for create, read, update, delete. I like to use "set" and "get" because it's short and sweet. But it doesn't matter, as long as the same thing always uses the same word.

If you're using a REST API, make sure your REST commands match your actions. Don't use POST for edit or delete, or PUT for read.

Here you create an animal using a single command, but you edit each animal using multiple commands. Why? Because Itzik from Eyal's team programmed ... Here you update each item in a dog using a different command, but  edit the same things in a cat using one command for everything. Don't do that.

Verbs set, nouns get. ParagraphCapital does not make the first letter of a paragraph capital, it checks if the paragraph is capitalized. Use a verb to set the paragraph. More simply, you set a state using setState, you get the state using state or getState.

Please avoid using Booleans, because they will always, always, (almost) always change to non-Booleans in the next version. You started the pet store with dogs. Then you added cats, so some developer added isDog to some commands. But other APIs defaulted to dog, so she used isNotDog. And then elsewhere she used isCat, just to mix it up a little.

Then you start selling elephants, snakes, giraffes, turtles, and fish. How many Booleans do you need to add now? Just avoid the problem. Anytime you want to add a Boolean, assume you're going to have to make it into an enumerated list up front.

Also, avoiding Booleans prevents your integrators from having to learn many new terms, especially if they're going to localize. It's one thing to learn a list of 50 or 60 words in your API, like "type" and "breed". Don't force them to learn all the English values, too. If your integrator is Spanish, he might not use "cat", he'll use "gato". So why should he have to learn that gato "isCat"? Minimize the number of tokens and avoid putting values in your action names.

 And I don't even know what this means. If you can tell me ...

For the same reason you shouldn't embed values in actions, don't embed units. Document the units. Also, the units may change, and you don't want to have to change the action names.

Here we have the animal type. The animal name. Number of legs. Number of heads, I think, or maybe number of tails. This must be the hair color and the breed. Then height? Length?

Anyway, don't do this. There is no need to add the number of legs once you know the animal type. If beagles are generally brown, there is no need for the hair color by default.

Here we wrap the parameters in a hash, so the meaning of each field is clear and we can leave out the defaults.

Try not to use a global state. For one thing, it avoids race conditions. For another, the application now has to use business logic to figure out what state it's in, how long to wait, how often to poll for the answer, and so on. Send the result back with an event, or a socket, or an email, or what have you. Let the application be dumb.

When considering resources, you may have dozens of ID fields for your database, your UI, some other system. Don't expose them all to the integrator; only give him what he needs. Also, don't return one kind of ID from one command and then require a different ID for a different command. We want to let him cascade the output of one command into the next one. He shouldn't have to look around for the information he needs.

Like actions, don't use Boolean parameters and don't embed the values in the parameter names.

I've seen this kind of documentation. It's not helpful. Remember, your result is being sent to an application, not a person. The application has to take the result and figure out what to do next, and for that it needs the exact list to parse. If something returns an enumeration, link to the enumeration or provide all the possible values.

Enums are good. Pass the enum code, not the value. This way the integrator can localize the results. So don't pass literals. In the second example, the developer tried to be clever by avoiding literals but concatenating strings together, but that's not useful if the result is going to a different kind of UI or if the language reads right to left. Pass the code and the values and let a utility do the substitution.

Don't use literals even if you don't plan on passing them on to the user. You might enjoy parsing a literal return value, but it's dangerous. If your API returns error code 22, the next person working on the API isn't going to change the return code to 23 just because it's his birthday. So you can expect it to remain the same. On the other hand, if your application parses the return value "no dogs found", it's going to break when the API changes all references to "dog" to "BarkBuddies".

The last example was also a problem, because you may have several results to pass back, and now you have to worry about parameter order. Pass the values back in a structure and let the utility figure out how to handle it.

What do we need documented for values? The range or possible values for the value. The units. Whether there is a certain subset of range or options that is recommended, like 4 legs. The default value or option, of there is one. Any dependencies between the values, like if that is above 4 then this has to be below 3. And where the implementer can get the value; which API returns the list of options for this value, so they know how to string the APIs together.

Speaking of documentation. A big problem with a lot of documentation is the writer assumes you know everything about the product before you start. Lots of documents start with "Welcome to our system. To log in ...." That's not helpful. Take a paragraph to orient your reader by explaining what your system is, and what the user can expect to do with it. Like a mini-table of contents so they know what to look for and if it's worth reading.

Don't waste their time documenting basic concepts like classes and programming ideas. But don't assume they know what your terms or products are or do. Don't just say it's a system for managing BarkBuddies. Tell them that a BarkBuddy is a dog.

Hyperlink so that they can get more information, so you they don't have to read the same information more than once. A content generation system like doxygen, JavaDoc, Swagger, etc does this for you.

Provide examples. Some people can learn the system straight from the examples, and in fact you may be able to get what you need just by cut and pasting the examples. And include a complete list of error codes that might be sent back.

Here's a very common source of annoyance. I hate documenting delivery packages, because I should never have to. They should be self-explanatory. Also, unless the API is a web page, no R&D team ever knows how the API is delivered. Is it a zip file? A DVD? How does the user get it? R&D teams don't even know this the day before, or of, or after the delivery.

But the delivery is the very first thing that the user interacts with. Please make it nice and clean. Make all the file names and directory names self-evident. Don't include parse.h and also parseNew.h or parse2.h . Clean it up! Remove everything that is not needed: files, directories, methods, and so on. Don't make the integrator wade through all these things he doesn't need, because he WILL call support and try to figure out what to do with them. Include the localization files and anything he can customize, like enums and configuration files.

Last tips. Consider a quick start guide to get the user up and running. Consider a cookbook that the user can cut and paste. And, if it makes sense for your API, consider a wizard that will generate the code with everything already in place without errors. Just make sure the wizard is up to date with the latest code changes.

Thank you.

Monday, March 09, 2015

Status Update

My life of chaos is particularly chaotic this month (and next).
  • I will be speaking on the topic of APIs this Thursday at DevConTLV. Namely: considering the design of your API from your customer's perspective: how not to annoy them.
  • When I find out more about how the gamification project ended at my old job, I'll write something up about it.
  • I found someone to take over my lease in Raanana, so I am moving back to Jerusalem by the of this month. That means boxes, movers, etc, etc.
  • Back in Jerusalem means that I will be back hosting the Jerusalem Strategy Gaming Club again, or co-hosting if Nadine wants to hang on to it some of the time.
  • During my vacation last week I made good progress on my book, but I need another 6 months of quiet work-time to finish it. I probably won't get to work on it again until mid-April, and then I will be involved in a number of side interface/gamification projects for friends who are developing web-sites.
  • Israeli elections next week and I don't have anyone to vote for, as usual.
Live long and prosper, my friends.

Thursday, February 26, 2015

I Went "Off the Grid" for Four Days


Brain Chemistry

My smartphone is indispensable; it is also physically altering my brain chemistry.

Every time my phone beeps, bings, buzzes, twirps, or tweedles, I actually twitch. If I hear a noise from my phone as I'm drifting off or early in the morning, a rush of adrenaline courses through my body. I have to check the phone or force my body to calm down. During the day, even if I don't hear or feel my phone buzz or ring, every few minutes I reflexively look to my phone or think about it. If I haven't heard anything for fifteen minutes, I pick it up to see if I missed something.

This is despite the fact that I do just fine without my smartphone 25 hours every week on shabbat (plus holidays).

The Opportunity

I had a week to relax between two jobs, but I wanted to make progress on my book, something that I find difficult to do in my house with the call of daily tasks, unlimited media on the internet, and my smartphone.

Hotels in Israel are (relatively) inexpensive right now, being off season. I picked the Leonardo Plaza hotel in Ashdod with 4 days off the grid: no phone, no internet, no email, no messages. For emergencies I was reachable at the hotel. I wanted to see if I could live without the grid for four days.

I invited my son Saarya and my daughter Tal to join me on condition that they used no internet or cell phones in my vicinity (I didn't want to hear disembodied conversations or the usual assortment of continuous beeps and tweedles). Saarya agreed to live off the grid like me for two days. Tal agreed to pretend to be off the grid in my presence.

What follows are separate reports: one about the hotel / vacation and one about living off the grid.

The Vacation

Ashdod is closer to Raanana than I realized, but it feels like a world removed from my home. The hotel is on the beach; it is mid-winter (which means a chilly breeze and cloudy weather) but it's still a beach: pretty dunes, nice waves, and colorful sunsets when it is not overcast.

Working in the hallway of the 9th floor
In front of the hotel is a gigantic, uh, eye / sideways flying saucer stuck in the ground. It's about 10 meters high and lit up with colored lights at night. I don't even.

Ashdod; an empty pool
The hotel is new, so everything is clean. The staff is friendly and helpful. When it comes to a choice between denying you something or giving you something, they give it to you; they really want to make you happy. The room comes with a plate of exotic fruits and bottles of San Pellegrino water and Marom Galil wine. It has cable TV. The first two days there were no movie channels; I thought this was because they sell movies POD, but the channels mysteriously appeared during the second two days. It has a hair dryer, water heater, fridge, and a comfortable bed and sleeping couch.

The hotel has a pool, but it's an outdoor pool that is not open in the winter months. I forgot to think about that. Tip: consider an indoor pool if you're vacationing in the winter. The hotel has a spa, but it costs extra for daily use, even the exercise room. I forgot to think about that. It has a business lounge which is adults only with a buffet of light foods and drinks, some computers and printers, and a private room. Access to the lounge is only for business guests.

My daughter and I spent some time on the beach but didn't get to see a sunset (the one day we waited for it, the sky was gray).





When I first arrived, I approached the reservation desk a little unhappy with myself for having picked a hotel without an indoor pool. Then I found out that, as an Israeli citizen, I have to pay VAT, which is 18% on top of the reservation price. I'm sure that if I search the hotels.com site I will find that little detail mentioned somewhere, but it came as a surprise to me. Bleah.

(If I had simply presented my American passport, they wouldn't have asked about my citizenship and I could have avoided paying the VAT.)

While processing my reservation I mentioned to the receptionist that I had forgotten to notice the lack of an open pool, the lack of free access to the exercise room, and now this additional not insignificant VAT cost. I asked if there were some way she could offer me something for my ... uh, disappointment. To my surprise, she gave me and my kids access to the basic spa (exercise room and jacuzzi) and the business lounge for free for the duration of our stay, which was generous. Also, the extra charge for my son turned out to be slightly less than I had thought, which was also nice.

The spa also has several rooms for expensive massages and scrubs of different kinds, including some for couples. The first floor of the hotel has a reasonably-priced salon / barber and a store that sells hair and beauty products as well as some of the usual hotel items.

The first evening the three of us spent with my cousin who lives in Nir Galim, a moshav just north of Ashdod.


The hotel breakfast is yummy, with a vast assortment of delicious foods and drinks, some made to order. We didn't eat any of the other hotel meals.

I got some good progress done on my book, spending much of the time in the business lounge. 

The hotel was generally an oasis of quiet except for the one day that a number of Israeli groups arrived, talking loudly in all the hallways and pushing all the wrong buttons in the elevators. That day the business lounge was unusable all morning and afternoon. The group clattered around, messily eating all the food and YELLING at and to each other while standing right next to where I was trying to work. When I asked them to be quieter, they moved two feet away from my table and continued to yell, anyway. I moved to in a mini-seating area next to the elevators on 9th floor. Things quieted down later in the afternoon. 

The hotel also has a little food court with drinks, pasta, salad, and pizza, reasonably priced.

During checkout, I asked reception if I could work in the business lounge for several hours again, even after I checked out, and they said yes.

On the way home I made a stop in TA to execute a Magic card exchange. I gave 15 cards and received in exchange 8,016 cards. Since the exchange wasn't entirely equitable, he also gave me an additional 40 NIS.


Those are stacks of 100 cards each.

Off the Grid

This turned out to be difficult.

After arriving at the hotel (using Waze, of course), I set my phone to airplane mode. But the reservation desk required my hotels.com reservation in order to calculate my VAT, so I had to briefly grid up to send it to them. In that brief moment, I saw at least three relatively important emails come in, including one that weighed on me for the rest of the evening: it was something from my previous work that I needed to respond to (a financial issue). I thought that it could wait until the end of the week, but if it was going to bother me the whole week, it didn’t really make sense to ignore it. When I returned to the hotel later that evening there was a message waiting for me at the hotel; the sender of this email wanted my response ASAP. So I gridded up again to print out the email, sign the form, scan it, and send it back.

In preparation for rendezvousing with Saarya on the first evening, I told him that I would meet him at a certain place at a certain time. I told him that, if I was late, or he wasn't there, within 45 minute, to proceed by public transport to my cousin. I had written down the necessary directions to get to our meeting point and from there to my cousin. However, as Tal and I walked to the car she told me that Saarya was not at the agreed upon location but at a different location altogether; apparently he had gotten a ride with someone and they had been unable to drop him off in that location since they had driven a different route. If my daughter hadn't left her phone on, Saarya might have been able to message me through the hotel reception, but it probably would not have gotten to me. So I gridded up again to navigate to the new location.

The next morning I checked to see if my scan had arrived by email, and it had. Back off the grid.

Without searching for a restaurant online, we were unable to find a nice place to eat on the second evening (I suppose we could have asked hotel reception) or print out a coupon. Luckily we didn’t have to pay for parking in downtown Ashdod, for which I need my smartphone. On a different evening, we didn’t eat at a restaurant in the mall because I couldn’t look up reviews on my phone. I ultimately decided to not eat there because it seemed under-populated; I assumed that if it was any good it would be mobbed with people. Maybe. I don’t remember how I made this kind of decision before the internet.
Working: Without any formal distractions, I found myself fidgeting every half hour or so. I had to get up and walk around. I had no YouTube to check, no news to see, no emails to check and file. Instead I wondered about them.

It turned out that, in place of movie channels, the hotel TV system included a primitive search for YouTube videos (and Facebook, somehow, but we didn’t try that). At night, we watched a comedy routine on YouTube instead of a random television program in the evening. This felt like cheating.

At one point I tried to sync my music to my laptop, but that required an internet connection to log into Apple; so I executed a brief grid up. Later I heard some music that I wanted to identify and remember. I had to grid up my phone for a moment to use Shazam. I also wanted to back up my work, which required a quick laptop grid up to access Google Drive.

On the fourth day, I turned my phone on in the morning to check for messages and received one from a prospective renter to take over my lease. I called him to discuss it. I told the guy that I would be unreachable again until the next morning because my phone / internet is off while I’m on vacation. I could hear his jaw drop. He told me how much he loved the idea and wished he could do it.

On the last day, I gridded up my phone and left it on. The Internet was still off on my computer. Luckily, my phone didn't beep too often.
All in all, it was a colossal failure and proof that I will be one of the first ones up against the wall when the revolution comes.