- Category: Miscellaneous
Note: The original title for this post was supposed to be ‘How is the Chromium Embedded Framework Documentation like a Sketch from Monty Python’s Meaning of Life?’ but the title was just too long.
I was getting some exercise yesterday and came up with an idea for an app I wanted to write. The app needed to work for Windows as well as Macintosh, so I started thinking about how I’d do it. I’m a big Delphi developer, and the recent Delphi tools support Windows & Macintosh, but I imagine other folks would be interested in this thing, so doing it in something that required a commercial software license to maintain didn’t make sense.
Next I started thinking about whether I could do it as a Cordova application. Windows is a supported platform for Cordova, so that would work, but Macintosh support is only available pre-3.x. I could probably dig up some work in progress OS X support somewhere, but if it’s not part of the core, it didn’t make sense for me.
Then I started thinking about Adobe Brackets. This code editor worked on Windows, OS X and Linux, so they’d clearly picked an approach that worked on each. It’s written using web technologies, so that would work for the app I wanted to build.
I started digging into the Brackets code to see how they’d done it. A while back, a colleague convinced me that Brackets was written in PhoneGap, but in reading around on the blogs it quickly became clear that it was created using the Chromium Embedded Framework (https://code.google.com/p/chromiumembedded/).
So, I started digging around in the CEF documentation and found a bunch of information. There was an introduction page at https://code.google.com/p/chromiumembedded/, a tutorial at http://code.google.com/p/chromiumembedded/wiki/Tutorial and some general usage stuff at http://code.google.com/p/chromiumembedded/wiki/GeneralUsage. Nice! I love it when an open source project has actual guides (that’s one of the things I love about Apache Cordova).
I quickly read through all of that material and quickly discovered that after reading all of it, I still didn’t understand how it ‘worked.’ The materials talked about where to download the stuff and how to build it, but nothing about how to ‘use’ it. The tutorial and usage guides talked about threads, callbacks, plugins and all sorts of stuff, but nothing about how to actually ‘use’ it. It’s clear that after I downloaded all of these files, I had something I could run and use, but how did I actually make it do what I wanted it to do?
I scanned through the stuff again and still didn’t see it. I saw all sorts of source code and highly technical stuff, but not what I needed to know to make an application that did what I wanted to do.
Even the Brackets source didn’t help me as it’s just the source code for the app and there was some external process for building it into the actual platform-specific executables. Sigh again.
Finally, I started searching around again to find some post or article somewhere that told me what I needed to do to make this thing my own. I finally stumbled on an article from Intel at https://software.intel.com/en-us/html5/blogs/an-html5-project-with-chromium-embedded-framework. Here they told me exactly what I needed to do to make the CEF my own – open a configuration file and edit a particular variable to point it to the web application content you want to load.
Ah ha! That’s what I needed to know. All that other stuff about threads, plugins, callbacks and so on is interesting, and that’s information I’ll eventually need, but for now I simply need to understand how to get started. All those pages of content and somebody simply forgot to add the important part – how to specify what content is loaded into the browser container.
So, apparently, for each target platform, you have to specify the content you want loaded in the browser, then use the build process to package it all together into the executable you need. Tada!
The issue for me is that developers working on open source projects are so excited about the technical stuff that they skip the getting started stuff and jump to the ‘important’ stuff. So much of the ‘documentation’ out there is written, in my eyes, from the standpoint that you already know how to do this stuff. I’m not kidding, most every time I take a look at one of these projects, I struggle to get past all the unimportant stuff in order to be able to find the simple, everyday, what do I do with this thing.
That’s why I write my articles and books the way I do – I assume NOTHING and expect that if you’re brand new to a topic, what I’m providing will give you everything you need. If you’re already familiar with the topic, I expect that you’ll be able to scan the content in order to find interesting tidbits. If you read the reviews of my more recent books on Amazon, you’ll see that people seem to agree.
Developers, please listen to me. When you’re documenting your stuff, assume nothing. Let me decide what’s important and what’s important – just document everything STARTING AT THE BEGINNING.
Want to hear a little confession from me? I’ve honestly never manipulated an XML document programmatically. Yep, that’s true. Want to know why? Because I could never figure out how to do so. When I first tried to do it in Delphi, there were some tools to help me do it, but no matter how hard I tried, I simply couldn’t find any documentation or example anywhere that showed me how to actually use the tools. The tool documentation clearly explained to me what methods and properties were available, but nowhere could I find anything that showed me how to create an object, assign it to some XML then retrieve properties from it. I’m sorry, but I’ve been a professional software developer for more than 30 years, but sometimes you simply have to show me how things work. I no longer have the patience to hack away at something for hours to figure it out.
Back when I was doing Java development on BlackBerry, I was trying to figure out how to use KSOAP (http://kobjects.org/ksoap2/index.html) to allow an application to consume XML-based web services. Like I said earlier, the docs explained the methods and properties, but never, nowhere, anywhere did it show me how to use any of it in a sentence. I wasn’t a heavy duty Java developer (never have been) so I simply didn’t have the background I need to be able to understand how to use this thing.
Again, I could have figured it out, but I had a wife, kids and some books to write, I simply didn’t have the bandwidth to plug through it in order to sort it out myself.
I’ll say it again: When you’re documenting your stuff, assume nothing. Let me decide what’s important and what’s important – just document everything STARTING AT THE BEGINNING.
JavaDocs can be…useful and interesting, but where’s the sample code? A simple requirement for each and every API, object, property & method is a code sample that shows the target developer how to use the thingie in a sentence. I know that would be boring for the experienced folks, but just don’t look at that stuff. For folks however who are not experienced with the particular technology, someone who knows just a little Java, lay it all out for them so they can use the stuff.
OK, on to the Monty Python Reference. So, how is the Chromium Embedded Framework Documentation like a Sketch from Monty Python’s Meaning of Life? The story I just told reminded me of the Sex education sketch (https://www.youtube.com/watch?v=PqI-28meTZ8) from the Monty Python Meaning of Life Movie. I’m not going to try to explain it here, watch the video to see what I’m talking about (warning, it is clearly a very adult topic), but what made me think about the video was the teacher’s comment about ‘why not start her off with a kiss?’
When creating documentation for open source projects, start with the simple, give the background beginning users need, before leaping off to the technical details that the more experienced developers need. Both approaches are needed.
Start us all off with a simple kiss before doing anything else.
- Category: Mobile Development
Whenever I publish a book with my publisher, they always pick one chapter and post it online for anyone to read. Picking the right chapter has always been a challenge for me because I want them to publish a chapter that’s interesting enough to make you want to buy the book while at the same time not being so good that you get everything you need and don’t buy the book.
Get it? Please buy my books. I write them because I like to write and think I have a special skill when it comes to describing technical topics, but at the end of the day I like the extra income. Buy my books, please?
Anyway, today, my publisher, Addison-Wesley/Pearson Education, published a chapter from my latest book. The book is called Apache Cordova API Cookbook, and they selected Chapter 1: An Introduction to Apache Cordova (http://www.informit.com/articles/article.aspx?p=2235541).
The publisher usually consults with me on which chapter to publish – they typically ask me which one or ones I would suggest then go off and pick one then put it online. This time they simply picked one and went with it, so I didn’t have any say in what happened here.
As the book is all about the Cordova APIs, so they could either have picked one of the API chapters or picked the only generic chapter: chapter 1. The chapter introduces you to the concept of Apache Cordova, what it does, how it works and what it’s used for. The book is targeted to mobile developers who have at least a little exposure to Apache Cordova, so this chapter is for those people who skipped the requirements and bought the book anyway – I had to give them a quick intro so they’d be able to understand the remainder of the book. It’s a good chapter and should give you a good teaser of what kind of stuff you’ll find in the rest of the book. If you like it, please buy the book. If you’re just getting started with Apache Cordova or Adobe PhoneGap development, you may want to take a look at the companion book: Apache Cordova 3 Programming (www.corodvaprogramming.com).
- Category: Mobile Development
Print copies of Apache Cordova API Cookbook arrived on Friday; my expectation is that they will be available for shipment from Amazon.com and other retailers by the end of next week.
This book, along with my Apache Cordova 3 Programming, provide 600 pages of coverage for Apache Cordova. These two books give mobile developers everything they need to be able to write cross-platform mobile applications using Apache Cordova or Adobe PhoneGap.
- Category: Mobile Development
I was poking around on Amazon yesterday and noticed that the Kindle edition of Apache Cordova API Cookbook was published back in June. You can get your copy immediately using the following link: http://www.amazon.com/gp/product/B00LB6X2SO/ref=as_li_tl?ie=UTF8&camp=1789&creative=390957&creativeASIN=B00LB6X2SO&linkCode=as2&tag=mcnsof-20&linkId=AXKNHCPITM4FNLNK.
- Category: Mobile Development
I keep hearing from readers who have just started reading my PhoneGap Essentials book. That book was published more than two years ago and PhoneGap has changed dramatically since then. The code in the book should still work - not much has changed on the API side of things. The content covered in the first half of the book however is no longer valid.
I rewrote the first half of PhoneGap Essentials last year and released it as Apache Cordova 3 Programming in December. That book takes the first 150 pages dedicated to PhoneGap development and PhoneGap tools and updates it for Cordova 3 plus expands it out to about 250 pages. There's an additional 50 pages on the APIs that covers them at a high level, but if you have the Essentials book you have the same information (just a little older). You can read more about the book at www.cordovaprogramming.com.
The second half of PhoneGap Essentials was all about the Cordova APIs, about 150 pages worth. I just finished rewriting that content (and expanding it to about 300 pages) and published it as Apache Cordova API Cookbook - the book will be in stores in about a week. You can read more about the book at www.cordovacookbook.com.
With these two books, you've got 600 pages of coverage for Cordova 3.
I think what’s happening, please correct me if I’m wrong, is that while the people I work with use Cordova, much of the world only knows of it as PhoneGap. I’m wondering whether not having PhoneGap in the title of my latest books is somehow hurting sales. As PhoneGap is a distribution of Cordova, you’d think that a book on Cordova would address both markets. If I change future book titles to have PhoneGap instead of Cordova in them, I may lose out on an audience that’s interested in Cordova and not PhoneGap. Sigh.
I tried to post a comment on the Amazon listing for PhoneGap Essentials letting folks know there was an updated version of the book available. Amazon refused to publish it.
I’m getting ready to start work on Apache Cordova 4 Programming, with a planned release of very late this year (December at the earliest) but probably early next year. I’m planning on expanding this book considerably and hope to get about 400 pages of content in there. When I get done, between the two books, I’ll have published more than 700 pages of content on Apache Cordova.
- Category: Miscellaneous
I mentioned this on twitter a while back, but I’m consistently amazed by how much effort is made by hackers to hack into my personal web sites. I’d be really interested in seeing what percentage of internet traffic is taken up by these types of efforts (not on my sites, but on content management systems overall). I plan on doing some analysis of this, but simply haven’t gotten around to it.
Anyway, I had some issues with the CAPTCHA on this site, and my comments plugin provider isn’t responding to any forum posts on the topic so I had to just leave the comments on and use the plugin’s moderation capabilities to weed out the spam. What’s interesting about this is that I generally only get spam on just one of my posts as shown in the figure below.
I don’t know what it is about that particular topic that attracts the spammers, but it sure does (to the tune of about 50 spam comments a week).
Apparently there’s some known bug in GeSHI and/or Joomla and the botnets are trained to look for it to see if they can capitalize on it. All the spam comes from the same botnet I think because the format of the message is always the same, just the topic and target change. In the old days, the comments would be entered by a human, or at least written by a human, so the messages had a real subject and real content. I’m really not sure why anyone things that comments with random characters in the subject and body of the comment wouldn’t raise red flags and get the comment deleted, but that’s what’s happening time and time again.
What I’ll probably do is switch out the comment plugin for another that actually works with Joomla’s built in CAPTCHA (see, CAPTCHA is an acronym so I’ll spell it that way, spam isn’t, so you won’t see me capitalizing spam that way). This is the second comments plugin I’ve used, and I hate to whack all the existing comments again, but I don’t get that many comments (only spam) so it probably isn’t a big deal.
People are reading these articles, right?
- Category: Microcontrollers & Single Board Computers
My dad was a tool geek, I’m a gadget geek. All my life I’ve been drawn toward technology. When I was a kid, I was constantly biking to Radio Shack to pick up one of their assemble-it-yourself electronics kits. I build radios, sound generators and anything I could get my hands on. I wanted to be an Electrical Engineer, but my grades weren’t good enough, so I went into Physics and Computers – go figure.
Anyway, my son’s a gadget geek as well. He’s 10, so all he knows is smartphones and tablets – every time I get a new device, he goes crazy for it and tries to show me how it works. Doesn’t he understand that I’m in the smartphone business and will always know more than him for at least a few more years?
Anyway, I’ve been playing around a bit with the Raspberry Pi (I’ve posted several articles here about my experiences) and I’ve always wanted to play with some programmable microcontrollers. My neighbor got me to take a look at some microcontrollers from Texas Instruments, but I’ve not done anything with them yet. I’m most interested in the Arduino, but again haven’t had time to play much with it...until now.
My son and I were discussing possible geek projects to work on and we decided to trick out a…well, it’s a secret, but I’ll write about it as soon as I can. We decided we needed a very small package for this project and I knew the Arduino was going to be too big. So I started looking around at smaller versions of the Arduino to use. The first one I found was the Teensy (https://www.pjrc.com/teensy/), its super small, and I think this is the one we’ll ultimately use for our ‘project.’
I wanted to breadboard this out first, so I picked up an Arduino Micro (http://arduino.cc/en/Main/arduinoBoardMicro) from Adafruit (https://www.adafruit.com/products/1086) – very nice, very small (although bigger than the super small Teensy). This one comes with headers (the Teensy doesn’t) and fits nicely into a breadboard as you can see from the following figure.
For this particular project, the Arduino needs to know how it’s oriented in space, so I picked up a Arduino Accelerometer module from Adafruit (https://www.adafruit.com/products/163). The 3g one seemed good enough, but since I bought that one the Adafruit team came up with a 16g so I picked up one of those as well. I imagine the 16g model will make it into our ‘project.’
I planned on working on our project this weekend, but of course forgot to pick up a breadboard. My son and I headed off to Radio Shack (oh, the memories from when I was a kid), picked up a breadboard, battery holder and a battery and got to work.
I first installed the Arduino IDE then connected the board to the computer and tested it worked by running the blink sample application. Next I wired up a single LED and got that working. After that, I wired in 5 LEDs, showing my son how to use the breadboard and make the circuit. With 5 LEDs working, I started playing around with the application code to see if we could come up with some cool blink patterns. I did them the hard way, turning each light on and off as needed individually, so I could show my son how the code worked. He quickly got bored, so when he went off to play with his friends, I refactored the code, added arrays and loops and created some pretty tight code. Tomorrow I’m adding a cylon pattern, it will be fun.
Next I added the headers to the accelerometer module; I wish it came with headers pre-installed because I quickly mucked up that task. Anyway, with the accelerometer wired in, the project can tell its orientation in space. Tomorrow my son and I will start programming different behavior depending on the project’s orientation in space. Like I said, I’ll write all about it once I get it all done.