Modularity in programming guides

I’ve read many programming guide books and tutorials. The one thing I’m looking for is, “I want to do X. What is the code I need to write to do just that?”

Many times, the author of the book or tutorial had mixed in other code or concepts into that. I want to know the simplest way to print “Hello World!”. I don’t want to include any extra libraries that don’t help with that. I don’t want any custom functions that makes printing a string any easier. I just want to print a string, ok?

The point is, the author already knows how to accomplish that task you want to learn. It’s when he gets, I don’t know, bored, that he adds other concepts to make it, I don’t know, interesting.

I’m not looking for the least number of code lines to write that accomplishes that task, although it’s usually that. I’m looking for the lines of code that just do what I want.

Because sometimes, I can’t differentiate the important from the extraneous. I don’t know, that’s why I’m learning, remember? This is especially important when I need to mix and match different concepts. If what I learnt has other extra stuff mixed in, then the resulting code has “more” extra stuff.

It’s like I want to mix X and Y, but got (X + dx) and (Y + dy). And I don’t know which parts are dx or dy.

Some authors make it clear which parts are the actual lines of code to accomplish X. Some authors are great at explaining stuff. I’m saying there are many others who don’t or can’t.

So when I wrote my Open XML spreadsheet programming guide, I made sure each chapter was modular. If not, I had sufficient comments and explanations so the reader knows which parts are the important parts. Each chapter was modelled after a major feature/function in the Excel software. How to style text, how to insert images, how to add more worksheets, that kind of thing. The Excel user mixes and matches those functions, so I want the programmer using the guide to be able to do a similar thing.

I got an email from a programmer who bought my guide that he liked to pick apart code to figure it out. I wrote a few custom functions but only because it made the code more readable. The full source code is given, so the reader is free to pick apart those functions and write his own (to better suit his needs).

I believe this is attributed to Albert Einstein:

Make things as simple as possible, but not simpler.

Be careful of encapsulating too much into just one function call.

Interview with Guy Kawasaki

Enchantment

I have the inestimable pleasure of having interviewed Guy Kawasaki, on his book Enchantment (which is released today on 8 March 2011). I’m still not sure how that happened (getting the interview, not the book)… I wasn’t sure if he’d respond, what with me being a small time publisher and all, but I asked him anyway with a short list of questions. He replied! That Guy is a great guy…

Guy Kawasaki

So here’s the interview.

Why is Enchantment important?

Enchantment is important because the more innovative and important your product, service, or idea, the more you will encounter resistance. You would think it would be the opposite, but the world usually resists a better mousetrap.

What prompted you to write this book?

Two major factors: my editor pounding on me for another book and my desire to combine the body of knowledge about influencing, wooing, and persuading people with my personal experiences as an evangelist.

Is Enchantment simply persuasion? How is it different?

It’s more than persuasion. Persuasion is usually applied for a specific transaction–you persuade people to do something like buy your widget. The purpose of enchantment is a deeper, longer-lasting, and more delightful relationship. Some companies persuade you to buy their laptop. Apple enchants people, and they buy a Macintosh, iPhone, iPod, iPad, and iAnything.

How can artists and scientists benefit from Enchantment?

Artists and scientists face the same challenges business people do: raising funds, communicating their passion, finishing their work, and then marketing it. All these stages require enchanting people and organizations–to change their hearts, minds, and actions.

[Ed: The “artists and scientists” part is a reference to my magazine, Singularity. Hey, I take care of my readers. *wink*]

Where can we find out more about Enchantment and your work?

The best place to learn more about Enchantment is
http://www.facebook.com/enchantment.

People can also tap these resources:

Speech video: http://www.guykawasaki.com/enchantment/video/
Web quiz: http://great.guykawasaki.com/
Facebook quiz: http://www.facebook.com/enchantment?v=app_6009294086
Infographic: http://www.guykawasaki.com/enchantment/infographic/

The best place to read my latest work is
http://www.openforum.com/connectodex/how-to-change-the-world.

Last words

Ok, so it appears there’s also a Facebook photo contest. Here’s the link:
http://apps.facebook.com/enchantmentcontest/entries

Wow, there’s a Nikon D3100 and an Apple iPad up for grabs!

The contest ends on 11 March, so you better hurry.

There are also wallpapers for your computer screen if you’re interested. Here’s the link:
http://www.guykawasaki.com/enchantment/wallpaper/

You can buy the book Enchantment from Amazon (aff link)

AONC review – be remarkable and question the status quo

The Art of Non-Conformity book

I wrote a review on The Art of Non-Conformity book (Amazon link), by Chris Guillebeau in the November issue of Singularity. Here’s an excerpt:

Interestingly, Chris compared the amount of time and effort spent working on his university thesis paper and his world domination manifesto. Both took roughly the same amount of time. But the former was read by only 3 people. His manifesto was downloaded more than 100,000 times.

When I read that, I was thinking, “That is so true!” My own thesis was read (presumably) by only 1 person, my advisor. My blog articles and this magazine are read by more than 1 person. Mathematically speaking, I’ve already done better. My work may not be as widely read as Chris’, but the concept is the same: more bang per word. Understand the result you’re going for.

Download the magazine with the entire review.

You can also buy Chris’ book too (Amazon link).

Library book dump as a filter

Some time ago, I was reading at my local library… what? Yes, the brick and mortar kind. Huh? What do you mean there’s Google and Wikipedia? Yes, I still use those. I just find the experience at the library interesting.

Anyway, I finished a business book, and placed it in the book dump. I don’t know what it’s called. It’s where you put the books you browsed, but can’t remember where it’s supposed to be shelved. Mis-shelving a book can seriously anger a librarian.

Well, I got myself another book, and was reading it when I noticed a young man loitering at the book dump. My guess was he’s about 16 to 18 years old. Bespectacled. A tad thin.

He surveyed the discarded books in the dump like a bargain shopper. He picked all of them up, and started filtering through them. Borrowing this. Borrowing this. Not borrowing that. Hmm, this looks interesting. Alright, borrow this too. Ugh, who reads this?

Curious, I went up to him and asked him what he’s doing, even though I guessed he was filtering through them. He was flabbergasted. He couldn’t give me a straight answer. Like he’s been caught doing something wrong.

I gave him a break, thanked him, and went back to my seat. He continued to process the books, and whaddaya know, there’s a computer beside the book dump for him to immediately borrow those books.

After he left, I was thinking, that’s an ingenious way to find the good books. I mean, if it’s there in the book dump, someone obviously found it interesting enough to take it from the shelf. If it’s interesting enough for someone else, it’s probably interesting enough for him.

That’s like the online equivalent of an RSS feed aggregator or a news site. I understand the need for information filtering. I also believe you should remember to exercise the decision about what information is useful or interesting to you, when you want to. Cultivate independent thinking, and don’t over-rely on others.

Speaking of news sites, there’s an online service, paper.li, that turns your Twitter feed into an online newspaper. It looks really awesome. You can look at mine here (ooh, the Vincent Tan Daily!). And follow me on Twitter.

Carcerian Stones – Retrieving an ancient tome

We’re continuing the D&D adventure story. Previously, we found our adventurers doing some crime scene investigation, were out of money, and located the wizard Arofell. We have Ryan the human DM, Dan playing Toth the goliath warden, James playing Heoriss the eladrin invoker, Ian playing Iofae the eladrin sorcerer, and Klenn playing Phileas the half-elf bard. And now…

*****

“Mr Arofell?” Phileas tried again, raising his voice a bit louder this time.
“Wha?” The man woke with a start. And a shrieking wail blasted from his hands.

Everyone covered their ears.

“Oh, you’re not Questin.” The ear-piercing shrieks stopped.
“Who’s Questin?” Toth asked.
“Oh, one of my colleagues who don’t really like me, and he’s been bothering me lately.” Arofell stammered. “Anyway, who are you?”

“We’re actually looking for you. The head monk at the abbey told us about you.” Heoriss replied.
“That would be Vand. A bit stiff, but I like him.”
“Do you know anything about a pair of babies being brought to Jorv, and some planar convergence that happened at the abbey?”
“Do you know anything about a foul black wolf-like creature?” Toth added.
“Do you know anything about this gold dagger?” Phileas showed the dagger from his accused murder scene.
“Do you have any quests for us?” Iofae asked.

James: Oh right, we need experience and money badly.
Klenn: Nearly forgot about our cash situation.

“Woah, woah, woah! Hang on a second! You don’t barge into someone’s lab and start barraging him with questions! Why should I help you?”
“Well, are you in need of assistance? We could help you cross the road?” Iofae suggested.

Ryan: Huh?

“We could help you cross your lawn?” Iofae continued.

Ryan: What?!
Dan: *snickering*
James: Oh… *muffled laughter*

“We could… help you cross your door?” Iofae faltered.

Ryan: Alright, what’s going on?
Klenn: I believe those are lines from the movie “Up”. Or at least of similar sentence structure.
Ryan: Ian!
Ian: Well… do you have anything we can help with? Other than crossing stuff.

“Well, I do have one small task I need done. Some days ago, a group of adventurers returned from an underground cave a couple of miles to the north west. They were lamenting the lack of any treasure. But one thing caught my attention. A book was mentioned. It was an ancient tome, set in the centre of the inner-most room they ventured in. They didn’t take it, because they didn’t know its value. But I do!”

“I want you to help me retrieve it. If you do that, I might be willing to help you with answering those questions…”
“Do we get to keep any treasure if we find them? Not that there are any left, since the adventurers probably cleaned them out…” Heoriss asked.
“I only need the tome. You can keep everything else. Don’t lose hope. Those adventurers aren’t the brightest men I’ve seen… They might have overlooked places…”

James: Alright! Treasure!
Klenn: So we go to the underground cave?
Ian: We need his help. We need money. We need experience. That cave’s gonna give us all that. Yeah, I think our next course of action is decided.
Dan: So we just trudge towards the cave now? *narrowing his eyes at Ryan* Any more skill challenges?

Ryan: Nope. And at this point, I wanna tell you that I’m upgrading all of you to 2nd level.
Dan: Why?
Ryan: To make up for whatever disadvantages you had. Like lack of cash. Whatever storyline I had in mind is already introduced, so you should have more stuff to play with. Besides, I want to keep the story moving. I can’t throw interesting stuff at you if you keep plodding at low levels. And we’ll stop for the night. I’m tired…

The underground cave

Dan: Alright, the cave’s next.
Ian: Feels like the Cave of Wonders in Kingdom Hearts.
James: Yeah, like “I wonder why there’s no treasure in this cave.”
Ian and Klenn: *laugh*
Ryan: Ok, you’re all just outside the cave. What are you going to do?

The party moved into the cave. It was pitch black, so Iofae struck a sunrod against the wall, and it cast enough light to let them see where they were going. There were some scuttling sounds ahead of them, and they stopped. And a pale insect emerged from view. And it’s the size of a man.

[some time later…]

James: I hate giant ants!
Dan: Ok, there’s a treasure chest beside the exit. Let’s open that.
Ian: No, wait!
Ryan: Too late.

As Toth stepped onto the granite tile in front of the treasure chest, a click sounded from the far left. The huge goliath barely dodged the javelin as he jerked himself back.

Ian: That’s why there are skeletal remains on the right of the treasure chest. They were the adventurers who weren’t careful. The javelin’s probably poisoned. But I wonder how the trap resets itself?

As the party stood around Toth, relieved that he was fine, the javelin started moving back. There was a thin wire attached to the end of the javelin, and there was a mechanical sound at its opening.

Ian: Oh a self-reeling javelin. Klenn, can I borrow your sword?

Iofae moved swiftly before the javelin was fully recoiled back into the wall, and severed the wire with quick slashes from his dagger and Phileas’ longsword.

Ryan: Impressive. The trap’s disarmed for good.
Dan: Now can we open the stupid treasure chest?

[some time later…]

After the party dealt with a few goblins, a run-in with some skeletons and a nasty mummy, they reached an open room with a dais in the centre. A wooden stand was lying on its side and a book laid close by.

James: Probably knocked over by the previous adventurers. Let me go check it out.

While Toth went looking for hidden rooms, Phileas retrieved the ancient tome and examined the book together with Iofae. Heoriss noticed something glinting at the bottom of the wooden stand, and found a curious object.

It was small and cylindrical in shape, fitting snugly into the palm of his hands. It was made of a material that’s complete transparent, maybe from some precious stone, judging from its weight. A thin gold line extended from the centre of a circular face to its circumference. There was also a similar line, silver in colour. As Heoriss examined it, the silver line rotated this way and that.

“I think it’s a compass.” stated Iofae.

James: *rolls d20 against Arcana*

“And magical!” Heoriss hissed.
“You keep that then.”

“Hey guys, there’s some writing over here!” bellowed Toth.

On the wall in front of Toth, was a short sentence written in flowing script. “To enter, offer a drop of sacrifice.” it read.

to be continued…

*****
P.S. The wizard Arofell was using what’s known as “Ghost Sound”, a wizard cantrip in D&D.

Chaotic arrangement of books and shelves

Pile of old books
[image by bunhill]

Rands wrote an article describing his love of books. (No, Rands isn’t his real name, and I respect his privacy if he chooses to use a handle.) He talked about the Amazon Kindle, and he also mentioned that he still liked to hold a physical book when he reads. Same here.

I’m going to answer the 3 phases of his book stalking process:

Phase 1: Where are they?

They are everywhere. Alright, only in the living room and my room. Of course I managed to find a couple of books hiding in a kitchen cabinet…

I don’t really have matching bookshelves to hold my books. It’s a cabinet here, a glass shelf there. The majority of my material possessions are books, so they sort of have a life of their own in my house. My father even built a bookshelf for me because he couldn’t stand some of the books just being stacked on the floor…

Phase 2: How are they arranged?

I think the only rule is: put the book(s) where there’s a space. This also means books are vertically and horizontally placed. Sometimes the shelf is too high, and the vertically placed books have some extra space above them, but not enough to place more books vertically. But I can lay books on their side on top of the existing books. Shove, shove, shove…

I’d make a terrible librarian… It goes with my messy nature

Phase 3: And what do you read?

I love fantasy fiction by David Eddings and Terry Brooks. There’s a couple of others, such as the Death Gate Novels by Margaret Weis and Tracy Hickman, and the science fiction ones by Michael Crichton.

There are also comic books, on the legendary kung fu master Chen Min, or Q in Detective Dan’s school or the Kindaichi chronicles.

I also have some books on business, self-help, and marketing. These are the non-technical books to complement the math and programming textbooks lurking… somewhere in those shelves…

And currently, the Dungeons and Dragons books command my attention. The fact that there are people who want to play tabletop RPGs with me helps with my interest.

Last thoughts

I think for an electronic version of books to be appealing to me, it has to be very “futuristic”. I don’t want to swipe from one end of the screen to the other to “flip” a page. I want to see a page being flipped, even if it’s holographically produced.

I don’t want to select a book from a list of titles on the screen. I want to see books in front of me, again holographically produced, for me to pick and choose.

It’s not just the book content I’m after. It’s the whole experience of reading.