10 Things I learned writing ArcGIS Web Dev

So it’s been almost two years now since I took on the challenge of writing the ArcGIS Web Dev book from Manning Publications. Recently I made myself a list of 10 things I learned in the process.

1. I didn’t think I could write Ok, that might be a horrible thing to say considering I have a book out that I’d like you to buy. When I say I didn’t think I could write I mean I didn’t think I could write a technical book. I like to think I’m pretty knowledgeable on the subject matter and to be honest a big reason I wrote the book was because I like to share things I learn on a regular basis. I figure if it’something I’m excited to learn about, I’m sure others would find it useful too. That and I knew it would make my parents proud. But besides my eloquent use of 140 characters or posting stuff on this blog, I hadn’t written anything of length since my thesis and even that I tried to fill with pretty maps to make my adviser happy (you rock Dr. Carroll!). I was under the impression that writing a technical book would require some higher level of cognitive thinking to do properly, whereas I can’t pass up a Buffy rerun on tv. Which leads me into the second thing I learned.

2. Editors have a hard job Editors know their shit. At least in my limited experience. I would pretty much brain dump half a chapter or so and my editor would somehow give me pointers on how to focus it or break things up. Now, when it comes to technical books, you need to consider that editors are not pros on the subject matter, but they are pretty damn good on figuring out how to get that information across and more importantly on directing me on how to do it. My editor taught me how to teach (thanks Susan!). Then there are the editors that take what one might think is well refined text and red pen it up like your high school English teacher after they had a bad weekend, but in a good way. I won the spelling bee at my elementary school two years in a row, so I’m pretty confident in my ability to spell, that doesn’t mean I can grammar. Those editors helped me to correct my grammatical ums and awkward pauses, so to them, I salute you. I learned a good editor(s) is a golden asset.

3. I’m still learning Dojo As a developer, I have made it a habit of keeping one eye on vim and one eye on a docs page. That’s just how I roll. When working with the ArcGIS API for JavaScript, I learned early on that I was going to have to get good at Dojo if I wanted any chance of getting good with the ArcGIS API. This is a fact of life. While writing the book, I had to really think about how much Dojo to cover and what not to worry about. Thanks to a great technical editor (thanks Brian Arnold!) I found I had some bad Dojo habits, like using declare.safeMixin when it wasn’t appropriate or some other details of the Dijit lifecycle I wasn’t totally aware of. The point being, there was still plenty of Dojo left for me to learn and I’m not foolish enough to think I have it all down either.

4. Teaching is hard This kind of goes hand in hand with #2 about editors. I’ve been told before that I have a knack for teaching/training. I never really thought of it like that, but trying to focus the things I know, or think I know into a format that doesn’t feel like I just squiggled some lines on a piece of paper with a nervous twitch isn’t easy. For me, it requires being conscious about what someone looking learn may be trying to get out of the experience, which leads into the next thing I learned.

5. Slow down to teach It’s not always just about emptying the bottle. You have to serve it in easy to consume shots or you’ll just end up sloppy drunk and sick and forget everything the next day anyway.

6. GIS is not required This probably sounds like heresy. I think there is a minimum amount of GIS knowledge required to build web mapping applications. When building an application you should know you probably can’t trust a straight-line measurement from China to Idaho. Do you have to know exactly what Kriging is? I don’t think so. Of course more knowledge and skill is valuable and worth knowing, but if you are coming from a different background, don’t let that scare you off. Learning JavaScript, DOM and CSS skills to get started will give you a hell of a lot more momentum in developing web mapping applications. If you want to up your game, develop some further GIS knowledge, it can only help you.

7. REST is king The ArcGIS API for JavaScript and the other APIS are like lieutenants in the mob. The ArcGIS REST API is Tony Soprano. The REST API essentially dictates what information the other APIs have access to. I make the point in the book that if you wanted to, you could write your own JavaScript API from scratch if you knew how to work with the REST API. That’s what esri-leaflet does. Sure the client-side requires building out the nuts and bolts of how tiles are loaded and cached and how to pan/zoom the map, but the REST API does all the queries, formats all the data and crunches all the requests. So if you learn the REST API, you’ll see aspects of the ArcGIS Web APIs just start to click.

8. Code review is priceless As a developer, one of my greatest fears is writing terrible code. I work in small teams and there is no formal code review. If I pass code to someone and they are like, wtf dude then I know I probably need to clean it up. I’ve read a number of books and articles on writing clean, readable code, but I could also have no clue what I’m doing. Thanks again to a great tech editor (thanks again Brian!) he pointed out a bunch of little things in my code that could be improved or maybe were not part of the modern Dojo way. Some things were just bad habits or how I learned to write Dojo back when it was at version 1.6 or something. Getting feedback on my code was one of the reasons I started writing this blog. Please feel free to review what I call code at github.

9. Simple does not mean easy This ties into #4. Writing the book, I tried to take some projects I had worked on and simplify them down to make them more general use and applicable to more situations. That’s not always an easy task. Even trying to explain how layers work took a few passes. It takes some work and some fine editors to help organize a pile of ideas into something that I think proves useful to someone.

10. I don’t know anything I can’t name all state capitals off the top of my head and I majored in Geography. There are tons of things I don’t know and even more I’m not even aware of that I don’t know. And that kills me, I hate not knowing. I feel like I’m in a constant state of the Imposter Syndrome. I try and approach everything I do as if I know nothing. I’m a lifetime learner. The entire time writing the book, I always double-checked what I was doing, eyeballing docs, checking old notes from presentations, watching old presentation videos. I relearned a lot stuff along the way. I couldn’t have written this book if I didn’t know what I was doing, but I also couldn’t have written this book if I let myself think I knew it all.

The book is now out and will be available in print very soon. If you buy it, I hope you enjoy it and learn something new. You can pick it up here.