Writing code is job one for most software developers, but learning to write about code is almost as important. Whether you’re documenting an API or showing off your own smarts, when you set out to write about what you think you know, it tests how well you really know the subject. As you write, you’ll often end up deepening your understanding of how the code works and honing your skills as a developer.
In this post I’m going to provide some tips and tricks for programmers who haven’t done much writing that will help you get started and find early success that fuels more writing.
This is a distillation of the first part of my “Writing About Code” presentation at Vermont Code Camp 2013. I don’t believe dumping my slides on the web helps. Instead, I’m pulling the most important ideas from my presentation into a few blog posts that are easier to read, digest and use to fuel your own work.
Why write about code?
There are many reasons to write about code. Maybe you want to share your knowledge and enthusiasm for programming, to market a product or teach customers how to use it, to promote your own abilities or because it is (or should be) part your job.
But I’d like to suggest another, more valuable reason, best summed up in this ancient wisdom from Seneca the Younger: Docendo discimus (“by teaching, we learn”).
Whether you write for yourself or decide to write publicly, you’ll start to explain something and, often as not, start wondering: Really? Is that all there is to it? What am I missing? How does this work? Engineers — your target audience — are always going to point out edge cases and pedantic details. Are you ready?
Go ahead and second guess your assumptions about your code, dig into the how and the why. You will most likely learn something new and improve your skill as a developer.
My code speaks for itself, right?
Unfortunately, your code does not speak effectively for itself — not for a wide audience anyway.
A code example does not replace an explanation. Sure, there are times when sharing a simple code snippet seems sufficient, but even then it’s usually posted in the context of a discussion… usually via social media.
If you show code you should explain the code, even if it seems obvious to you. You wrote it, so of course it’s obvious. But there are many other people — your potential readers — who are trying to learn. If the concepts you present in your code were obvious, these people wouldn’t need to be reading about it.
Many of your readers are going to be far less accomplished programmers. Believe it or not, by simply taking the time to research and write a blog post, you become an expert. Help them understand.
In fact, this is where a lot of official documentation falls down. It shows the most basic example, but frequently fails to take it farther than that. Then it expects you to jump straight to a complete sample app. There’s often little explanation of how you get from A to Z.
You may think it’s all be written before. What do you have to contribute? We’re still figuring this programming thing out. Every bit of knowledge helps move the profession forward. People are still writing about C. People are still writing about Cobol! Your unique approach to the subject may be the key that unlocks a problem for some reader.
Fear of writing… or how I learned to stop worrying and just write
The most important tip: Write something. Anything. Just get it out of your head and on the screen. Make time to write every day. 100 words or 30 minutes or whatever seems achievable on a regular schedule. As you become more comfortable, try increasing your target time or word count.
Do make it a habit, but don’t make it a chore. If you get stuck, stop and come back to it later.
Use the tools and languages you use every day. Write about the thing on your mind right now. A distraction that often gets in the way of writing (and probably coding, too) is obsessing over the “best” tools. There is not best writing tool, and messing with different editors just keeps you from writing. Word is fine, but so is a basic text editor… your IDE will probably work fine if that’s where you’re most comfortable and productive.
Don’t underestimate the usefulness of pencil and paper.
A helpful approach for avoiding editorial paralysis is to commit yourself to at least two trips through the material. I think most people get in trouble by trying to edit while they write. The result is usually not writing. An outline or a list of the major points you want to touch on works well, but from that starting point, try to write stream-of-consciousness. Get as much down on paper as possible.
Don’t fixate on the entire article. Work idea by idea, section by section. Each sentence is a building block for a paragraph, and each paragraph is a building block for your article.
Although correct technical details are important, as are correct spelling and capitalization, don’t get hung up on researching each topic as you write. If there’s something I’m not sure about or that needs more detail, I prefer to make a note to myself inline to go back and double-check or add more information later. Better to have the sketched out skeleton of your writing in place rather than getting side-tracked by research from writing at all.
Write a complete first draft before making any edits or revisions. That includes fretting about spelling, grammar, and so on. Once that draft is complete, then read it through, fix mistakes, add details, re-order, refine, and refactor as needed.
Focusing your big ideas into byte-sized pieces
A common problem for writers is determining the scope of what you’re going to write about. If the idea is too big, you’re likely to run into two problems: You either never finish (which is frustrating) or you skip over important details to finish (which leads to a poor finished product).
At least when you’re starting out, focusing your writing on small, achievable goals will help you succeed more often, giving you confidence in your writing and setting up a positive feedback loop of writing, accomplishment and more writing.
It’s often better to focus in on a very specific detail and write about that as clearly as possible. You have a more clear goal for the writing in front of you. You can often think around the smaller concepts more easily. Plus, there’s less to write — you’ll finish more quickly.
You can stitch together other small, focused bits of writing into episodic blog posts (Oren Eini does this very effectively on his blog) or into a longer article.
You’ll often find that small topics aren’t really so small when you dig into them. Think about not just how you implement a solution, but how it works… and why. What are the edge cases? What’s helpful to know? How much is boilerplate, implemented for you by the IDE or framework? Can you explain how that all works? How much is “received wisdom” about how things should be done, or code IntelliSensed in with a keystroke?
In fact, I suggest, as an exercise to practice writing about your code: take a chunk of code and explain it block by block. I bet you’ll discover quite a few assumptions you’ve made along the way. It doesn’t have to be your code. Document some random source code just for the practice.
Avoid pasting in large code blocks. It hinders the flow of reading and distracts your reader while she deciphers the entire block. Instead, break your code into digestible snippets if at all possible. Explain each bit as you go through. At the end you can provide the entire code block for copying and pasting, or link to a file/repo.
I suggested digging into the details, but you don’t always have to explain how deep the rabbit-hole goes. Most of the time, unless you’re writing basic programming tutorials, you shouldn’t have to explain how a for loop works, or what you’re iterating or basics like that.
Instead, think about the conceptual building blocks of your idea. Break code down into snippets that let you discuss it in terms of those building blocks. For nuts and bolts coding, that may mean discussing code line by line within individual methods. Other times you might discuss the overall construction of an entire class (suitably simplified, if possible) or of classes within an application.
As an example, take a look at Chris Eidhof’s Lighter View Controllers article at objc.io, which examines code organization at the class and file level. Then consider Peteris Krumins’ Bash One-Liners Explained series of posts, which by definition examines one line of code at a time in great detail.
What to write about?
Still not sure where to start? Here are a few ideas:
- Write about what you’re enthusiastic about
- Write about what you’re curious about
- Write about what you’ve done that makes you feel smart
- Write about a problem you had to solve
- Write about what annoys you or makes you smile
- Write about what you don’t understand: you’ll learn along the way
There is a audience out there eager to learn. Start writing for them. It will do you some good, too.
People love to learn how things work… and why.
People love when someone else solves their problems.
People want to know what they need to know and where to find it. They want to know how to get started, and then they need to be handheld from the simple to the more complex.
People always appreciate clever and useful utilities and code snippets, and tips for how to use them.
Stop reading, start writing
You have some basic tools for getting started. Now put them to work and get started writing something every day. You don’t have to publish it. Just keep a journal for practice… a journal of ideas, which you might return to later for material as you become more confident in your writing.
This is part of a series of posts discussing the main points of my “Writing About Code” presentation at Vermont Code Camp 2013. Here are all of the posts in the series:
Now, get writing…
Update 2/22: Revised to address bug fixes in TextDrop. See my notes below.
In 2011, I wrote a post about Crossplatform Note Sync with Dropbox. For the most part, the workflow and apps I wrote about still work well. However, times change I thought it would be a good idea to go back and check on some new developments, both platforms and tools, that may give you some new note-syncing options.
In a few cases, new features make this workflow even more flexible. For example, Elements now allows you to select which folder it uses for syncing files.
One new development the deserves a look is TextDrop, an online text editor for Dropbox.
TextDrop is a web app that lets you access your Dropbox folder and edit, in the browser, any text-based document there.
I learned about TextDrop from Gabe Weatherhead of Macdrifter, who’s written some great introductory posts about it, most notably here and here (plus an interview with TextDrop developer Sam Nguyen that’s worth a read).
There’s not much to the app: one pane shows the contents of the current Dropbox folder, the other lets you view and edit the selected file. It provides minimalist text-editing features, plus MultiMarkdown preview.
There are options for enabling hard tabs, non-text file previews and full-text search. That’s pretty much it.
The good news is that TextDrop works fine in some popular desktop browsers, specifically Chrome, Firefox and Safari. TextDrop also works in Mobile Safari on the iPhone and iPad, though the site is a bit too cramped for regular use on the smaller phone screen.
The not-so-good news is browser compatibility. IE 6 and 7 are not supported by design,
and I couldn’t get the site to load in IE 9. Google Chrome Frame might help. Windows 8 is not supported. No joy in Opera, either. The site does load on Mobile Safari, but it’s marginally useful at such small screen sizes.
Update: After a recent update to TextDrop 3.8.3, the site loads and works correctly in IE9. I haven’t tried IE10 yet.
TextDrop is priced on a sliding scale, the actual subscription price rising a small amount with each new user. This is similar to the pricing scale used by Pinboard.in. You lock in a yearly subscription fee based on current price when you sign up.
I purchased a subscription (at around $10) because TextDrop does add some helpful flexibility to my writing work and I want to support Sam’s continuing development of the app. The price recently jumped to almost $30.
Is TextDrop valuable at the current price?
If you work mostly within the toolset currently supported — namely, Chrome, Firefox and Safari — TextDrop can be quite useful. Once authorized, your documents are just a browser bookmark away, wherever you may be working.
Although TextDrop has some missing spots in its compatibility checklist, it does cover the most popular platforms. Expanding compatibility to Windows 8 and Windows Phone 8 could win TextDrop some vocal supporters. On the other hand, improving mobile compatibility and expanding the editing capabilities probably addresses the needs of a larger user base. I’ll be watching with interest.
Update: It’s worth noting that Sam is making regular updates to the service and making changes in response to user feedback. Not only did he fix the IE9 loading issue within a week of my pointing it out, but he also fixed a minor tab-spacing bug as well, among other things. This is the kind of service where your subscription dollars are really going to support the work of an independent developer, who in turn is working hard to address the needs of his paying customers. I like it.
The State of Things
TextDrop aside, how has the cross-platform document editing scene changed since I wrote about it in 2011?
Dropbox seems to have become the most reliable and flexible service for syncing your data, reinforcing the reasons I settled on it in the first place.
Apple’s iCloud service still isn’t ready for prime time and is, anyway, currently restricted to Mac and iOS.
There are two reasons I’m wary of this service. First, given the history of support for now-defunct sync services like FolderShare/LiveSync and Live Mesh, I wonder how long SkyDrive will stick around.
Second, you have to wonder about support for competing platforms with Apple reportedly rejecting updates to Microsoft’s SkyDrive iOS app.
Text editing apps have proliferated. I run Sublime Text 2 on all my desktop systems — Linux, Mac and Windows. For iOS devices, Brett Terpstra has compiled an extensive list of iTextEditors - iPhone and iPad text/code editors and writing tools compared. I’m still happy with the latest updates to Elements.
I’m less familiar with the Android text-editing scene, but LinuxLinks has a roundup of the 8 Best Free Android Editors. Here’s another Minimalistic Text Editor for Android, though I’ve seen a few forum posts recommending vi. Seriously.
Code-focused editors are another, more specialized category. I’ll be looking into that soon…
Updated below on 1/3 and 1/16
Online services are going to steal all of our content and use it to enrich themselves. Or maybe they’re not. It makes for great paranoid headlines whenever a popular site updates their terms of services, but what’s really happening here?
IANAL and have no particular expertise in the areas of IP law, so you’d be wise to rely on your own judgement and the advice of an attorney rather than my insight. However, I think there’s a lot we can learn from a close reading of actual terms of service and a little common sense.
Schneier mentions the recent dust-up about Instagram’s terms of service, and if you’ve been paying attention, you also know that Twitter, Facebook and other services have faced similar controversy over their TOS language.
The general uproar is something along the lines of:
“OMG ALL YOUR CONTENT ARE BELONG TO [service du jour] AND THEY CAN DO ANYTHING THEY WANT WITH IT!”
What’s this all about? Why is [service du jour] suddenly stealing everyone’s photos, wry observations, presentations or whatever? And what are they going to do with all this booty?
All Rights Reserved
The problem rests in some fundamental misunderstandings about how we use copyrighted works.
When you create something — write a tweet or a blog post, take a photo, sing a song and so on — the copyright for it is granted automatically (and in most cases, to you… though there are exceptions). If someone else wants to use it, they need your permission: you can grant a license for them to use that writing or photo or song under certain conditions.
And that’s exactly what’s happening here. You take a photo. You have a copyright on that photo. You upload it to Instagram. For them to do anything with that photo, you need to give Instagram permission — a license — to reproduce your copyrighted content and save a copy on their server.
Say you want Instagram to let your friends see the photo. You’re smart and know how computers work; think about the further consequences: Instagram has to make and distribute copies of your photo for each person who wants to see it. Maybe they distribute files around to servers for load balancing or CDN-style distribution. More copies. Hopefully they back up your data. More copies.
They need your explicit permission to copy and distribute your copyrighted work.
Of course, lawyers being lawyers, and corporations being corporations, they use very-broad-and-yet-very-specific language to cover their asses in all the ways they can possibly think of, plus a few ways both you and they haven’t imagined yet.
So you end up with terms of service language that sounds like OMG ALL MY FILES BELONG TO…
Take a deep breath. Maybe it’s not that bad after all.
In a previous life, part of my job involved proofreading EULA text for software installers. Yes, it was dull. But, the benefits! If you’d ever read through all of a EULA, a rental or mortgage contract or any similar legal document, you’d know that most of the language looks remarkably similar from one contract to another… it’s boilerplate. Why reinvent the wheel? If it works in one situation (and holds up in court), use it again and again and....
In order to provide you with the Service, it is necessary for you to grant Prezi certain licenses to your User Content.
With respect to Public User Content, you hereby do and shall grant to Prezi (and its successors, assigns, and third party service providers) a worldwide, non-exclusive, perpetual, irrevocable, royalty-free, fully paid, sublicensable, and transferable license to use, reproduce, modify, create derivative works from, distribute, publicly display, publicly perform, and otherwise exploit the content…
(My emphasis here and throughout, by the way, unless otherwise stated.)
That sounds pretty sinister. Promising to “exploit” is rarely a great way to make friends. In addition, Prezi requires you to grant a similar license to anyone who views your public content:
When you upload User Content on or through the Service, you also hereby do and shall grant to each user of the Service with whom you share your presentation a personal non-commercial non-exclusive license to access and view your User Content.
Yikes! What are they doing with my presentation?
But hang on. Think back to what I metioned earlier. They need your explicit permission to make any copies of your content that live on their servers or move around their service, any copies displayed to other users of the service and any copies needed for features of their service they haven’t implemented or even thought up yet. That is what your “worldwide, non-exclusive, perpetual, irrevocable, royalty-free, fully paid, sublicensable, and transferable license” enables Prezi to do without fear of being sued for copyright infringement.
I mentioned my interpretation of the license terms to Hal, who replied that “Microsoft has no rights other than those necessary to operate [the] service”, offering Microsoft’s terms of service as a counterexample to Prezi’s.
It’s a fair point to the extent that Microsoft Services Agreement section 3.1 does explicitly state “[W]e do not claim ownership of the content you provide on the services. Your content remains your content....”
I believe that to be entirely true and put in fairly straightforward terms. Further, they make the entirely valid point that other people may see, save and reproduce copies:
If you share content in public areas of the services or in shared areas available to others you’ve chosen, you agree that anyone you have shared content with may, for free, use, save, reproduce, distribute, display, and transmit that content in connection with their use of the services and other Microsoft, or its licensees’, products and services. If you don’t want others to have that ability, don’t use the services to share your content.
However, if we read a bit further, we’ll see something a bit more like that Prezi license language start to show up:
When you upload your content to the services, you agree that it may be used, modified, adapted, saved, reproduced, distributed, and displayed to the extent necessary to protect you and to provide, protect and improve Microsoft products and services.
…you are granting Microsoft, its affiliated companies and necessary sublicensees permission to use your Submission… including, without limitation, the license rights to: copy, distribute, transmit, publicly display, publicly perform, reproduce, edit, translate and reformat your Submission… and the right to sublicense such rights to any supplier of the Services.
For better or worse, you’re going to see language like this being used by pretty much any significant player in online or cloud services.
Here’s Twitter’s version, under the section helpfully titled “Your Rights”:
You retain your rights to any Content you submit, post or display on or through the Services. By submitting, posting or displaying Content on or through the Services, you grant us a worldwide, non-exclusive, royalty-free license (with the right to sublicense) to use, copy, reproduce, process, adapt, modify, publish, transmit, display and distribute such Content in any and all media or distribution methods (now known or later developed).
As the tip on the page notes, “This license is you authorizing us to make your Tweets available to the rest of the world and to let others do the same.”
Let’s take a look at Facebook’s Statement of Rights and Responsibilities, under “Sharing Your Content and Information”:
You own all of the content and information you post on Facebook, and you can control how it is shared through your privacy and application settings. In addition… you grant us a non-exclusive, transferable, sub-licensable, royalty-free, worldwide license to use any IP content that you post on or in connection with Facebook (IP License).
Or maybe you should check out the “Your Content in our Services” section of Google’s Terms of Service:
Some of our Services allow you to submit content. You retain ownership of any intellectual property rights that you hold in that content. In short, what belongs to you stays yours.
When you upload or otherwise submit content to our Services, you give Google (and those we work with) a worldwide license to use, host, store, reproduce, modify, create derivative works…communicate, publish, publicly perform, publicly display and distribute such content. The rights you grant in this license are for the limited purpose of operating, promoting, and improving our Services, and to develop new ones.
It’s a little harder to find (conspiracy theory anyone?), but Apple’s iCloud Terms And Conditions aren’t much different:
Apple does not claim ownership of the materials and/or Content you submit or make available on the Service. However, by submitting or posting such Content on areas of the Service… you grant Apple a worldwide, royalty-free, non-exclusive license to use, distribute, reproduce, modify, adapt, publish, translate, publicly perform and publicly display such Content on the Service…
Birds do it, bees do it. Everybody on the web seems to do it. Let’s do it. Let’s accept that these license terms are basically industry boilerplate and move on.
Fox In The Hen House
Just to be clear, I’m not trying to belittle the comments made by Hal or Bruce… or anyone else who has concerns about this widely used, easily misunderstood — and perhaps easily abused? — licensing language.
I believe it is essentially boilerplate and meant to cover legitimate business use of our photos, videos, jokes and memories. Thus far, I can’t think of any businesses that have, in fact, appropriated user content for reasons not intended by the user. And given the backlash resulting just from the suggestion that it might happen, I can’t see why any sanely run business would try to do so.
But the ideas that are unacceptable today may become more acceptable tomorrow. Perhaps a future startup tries explicitly employing user content as part of its service, creating a wedge that makes the practice tempting where it was previously taboo. Of course, people tend to do stupid things, so maybe it’s just a matter of time for someone to exploit this broad licensing language, consequences be damned.
In the meantime, the bold headlines seem more click-bait than Cassandra.
Update: Well, well, well… Ryan Singel points out that BuzzFeed is already raising significant investment funding on a “biz model of willful copyright infringement.” Sure, they’re taking liberties with photos folks have posted to other services — you haven’t licensed them anything — but is this the “wedge that makes the practice tempting where it was previously taboo,” or an outlaw site, doomed to failure?
My point stands, however: these terms of service aren’t the problem (yet). Bad actors are.
Update 2: Today Reuters reports that News outlets improperly used photos posted to Twitter. According to the story, a reporte at Agence France-Presse took photos that photographer Daniel Morel had posted on Twitter, used them in an AFP story without permission, then passed them on to Getty Images, from whom the Washington Post procured the images.
AFP had argued that Twitter’s terms of service granted it the right to use Morel’s images.
The judge, though, said that while the service terms do allow the reposting and rebroadcasting of users’ images in certain circumstances, such as “retweeting” them, it does not grant a license for commercial use....
Twitter was not a party in the case. “As has always been our policy, Twitter users own their photos,” a Twitter spokesman said.
As before, I think this is a case of misappropriation — and a journalist at an organization of this stature should really know better.
Bonus: Mike Wats merged my pull request, and now the new archive code is part of the core staticDimension code on Github.
Not bad for a first attempt at coding in public.
But it never really clicked for me. Until this year, when I started to put some real effort into not just learning about coding, but actually putting fingers to the keyboard and making something — anything! — execute and do something — anything!
I’ll write a bit more about the experience of putting years of theory into action another time. Right now I’m going to share my experience of doing one of my first real coding projects, however small it may be, right out in public for everyone to see.
As I mentioned in the previous post, my primary goal for this project was to create a simpler, easier to navigate archive of my blog posts that no longer appeared on the home page. Simple solution: create a single page with a listing of past posts. In the unlikely event that someone wanted to find one of my old posts, it would be easy to simply go to the archive page and either scroll the list or Command-F find the desired post title — responsibilty on me to write relevant post titles.
The quick-and-easy plan for adjusting the code was to comment out the archive code that I didn’t want to use and replace it with a modified version of the code used to create the home page. It just needed to grab the titles and bylines (including publishing dates) and make the title a link.
There were a few other details, such as including a link at the end of the home page to archive, so the intrepid reader who scrolled all the way down could fine more posts. And that was about it for version 1.
Making it Work for Anyone
Those tweaks would have sufficed for my site, but I felt a need to take the next step in my development as a developer: write code good enough for other people to use, not just me.
To my mind, that meant three things:
Make my changes a new, additional feature to the existing project, not just a tweaked version.
Write my feature in a way that defaults back to the standard functionality if anything goes wrong.
Try not to add much additional overhead to site updates.
As a bonus, I thought it would be interesting to submit a pull request and see if Mike would add my feature to his codebase.
I’m not all that self-conscious of the triviality of my changes. It adds a feature I want, it works, it doesn’t remove any functionality other users might use. The first part was pretty easy. The second part added a bit of a challenge.
After thinking about the problem, it seemed like the most straightforward approach would be to add a setting. If it’s set to true, my new feature gets used. A setting of false or any other value reverts to the default behavior.
/* Single-page Archive This setting enables a single-page archive instead of the default day-month-year folder archives... A value of 'true' enables single-page archives. Any other value currently uses the default archive format. */ $this->settings['singlePageArchive'] = true;
I left this as false by default as well, so anyone who pulled the code to an existing site would not be surprised by new, unexpected archive page creation. This was an important point for me: it should not break anyone’s existing site!
From there it was a fairly straightforward task to put in my new archive creation code (adapted from Mike’s original home page cration code) along with a test for the singlePageArchive setting.
That took care of my first two goals, adding new features on top of the existing ones, and not breaking the old, default features.
This is probably old hat to many programmers, but it was a pretty big step for a guy who’s worked with programmers for many years, yet never written anything comprising more than 20 or 30 lines of rudimentary Python.
For starters, I’d never spent much time wading around in PHP before, and what I had done was mostly cut-and-paste coding to quickly solve a problem. The contact page on this site [ed: deprecated in a redesign] is a great example: someone elses’s code example with a few tweaks to suit my needs.
The good news is that, over the course of many years, enough programming logic permeated my thick skull that I could follow the code, understand what it was doing, and find the interaction of functions I needed to modify — even though it was in a foreign language.
The moral of this story is that you can achieve quite a bit with a little knowledge, reference material on the web, some careful reading and persistent effort.
What I’d Like to Do Better
There’s definitely room for improvement. I have few illusions about that. So there are a few goals for the future:
Testing is something I’ve read much about, but haven’t done properly yet. This is a high-priority area to learn and incorporate into my future projects.
My third goal was to avoid adding overhead to site operation, and that may be one area where I’ve failed. As implemented, any action that adds, changes or removes articles updates the entire site to make sure the archive page gets updated. A better way to handle this would be to test whether the changes actually affect the archive and only update the affected pages instead of rebuilding the site.
For a small site, this probably isn’t an issue, but it would be more “right” in my mind.
Finally, I’ve been wanting the ability to update menus and sidebars without having to edit each page template individually — a source of several errors. So expanded templating would be nice and is on the to do list.
Polished Is Not a Requirement
Now, while I saw putting some spit and polish on my code as a prerequisite to sharing, it’s certainly not a requirement. In my case, I felt it set a reasonably high bar for my own work as well as making sure my contribution played well with someone else’s existing project.
This seems to be the quality bar many others set for contributing to existing projects. Play nice. Make your changes clear. Provide passing tests. It’s just good manners.
But there are plenty of cases where putting code up in public for other people to see, play with and discuss can help move an idea forward. The sentiment is pretty well summed up in this exchange between Kelly and Brandon:
@kellabyte always. Code doesn't mature in privacy.— Brandon Williams (@faltering) September 16, 2012
That led to Kelly posting her initial swag at writing her own home-brew column-oriented database, Dazzle, an attempt at understanding the inner workings of Cassandra by implementing her own version of it.
One thing I’ve learned from posting Dazzle on GitHub & code pastes in the past, embarrassed about your code only holds your progression back— Kelly Sommers (@kellabyte) September 26, 2012
Success or failure, the kinds of fast, constructive feedback loops enabled by Github and similar tools are great for learning. So there’s very little reason to not share your code.
I never doubted that public code repositories were a great idea, and the proliferation of choices — Bitbucket, Github, Google Code, SourceForge and others — indicates it’s a pretty popular and successful model for collaboration. And though I’d downloaded code and applications many times from these services, I never thought I’d write any code worth pushing back.
But my tiny triumph underscores how important it to just dig in and try something new. You can keep it to yourself if you want, but striving to make something you’re willing to share sets the bar high, and sharing opens the door to feedback, learning and improving. Whether it’s coding or writing or drawing… whatever floats your boat. Create. Share. Grow. Repeat.
Once upon a time, the Internet was a much smaller place, but still full of incredible things that suddenly made our pre-Internet world seem small and plain by comparison. But you couldn’t find it all very easily. It was like wandering around in the dark and occasionally stumbling upon something interesting.
And then there was search, and it was good.
Making search better and better taught me that the information was out there, and I could find it.
It also gradually led me to expect that, as search improved, it would begin to understand my question better and return more accurate, relevant results.
Eventually, however, search engine developers seem to have stopped trying to understand my search expression in more sophisticated, relevant ways. They know a lot about me: where I am, what I search for, what I look at, what I buy… and they make a business off that. But I’m not the customer anymore. And their attention turned toward making the service better for the actual customer…
Making search better and better for marketers is teaching me that the information may be out there, but whatever I enter as a search term, it fails to understand the nuance of my question no matter how I phrase it and returns only marginally related results, mostly for products or services I can buy.
Page after page of inaccurate results, and all for the wrong thing to buy.
It gradually leads me to expect that our industry will pursue progress and innovation just far enough to capture an audience. And from that point on it’s all scaling up, monetizing and, mostly, showmanship. But not giving me a better product.
Eventually more folks realize that they’re contributing to the business, but not getting anything back out of it. So the audience goes away and the search folk are left wondering where they went wrong. Should have written the service in a different language? Didn’t scale right? Outmaneuvered by competitors?
No, just forgot why what they started was important in the first place. And that was not so good.
So, to live happily ever after, the good folks wandered off elsewhere to find and share things and maybe, over time, search becomes a bit less relevant. Because they forgot who their real customers were, and why they started doing what they were doing, and we never really made any progress at all.
I bet you can apply this same parable to a few other online services, too.
We had some friends and their children over for Christmas/Hanukkah dinner, and the playhouses I wrote about last week got some serious product testing.
There were seven adults in the house trying to have some grown-up conversation, and six kids — 1, 3, 4, 5 and two at 8 years old — simultaneously climbing into, out of and around the playhouses.
Eventually the red door came off the cottage, and some wrestling between three of the boys tore part of the lower-front corner of the cottage. Fixed it with some packing tape this morning.
I think some of the parents were appalled by what their kids were doing and I had to repeatedly tell them it was all in good fun. I wanted the kids to do their worst so I could see where the playhouses failed. We were all amazed that they provided as much fun and held together as well as they did.
Best playtesting ever.
I don’t know if other kids are like this, but our girls have demonstrated again and again that an empty box can provide as much engaging play time as the toys that may have come in it. And certainly more fun than the boring mommy and daddy stuff that arrives in the bigger boxes.
Of course, the bigger the box, the bigger the possibilities… which ultimately led to making these playhouses for the kids.
They were easy to build and I will explain how you can build some, too.
You will need:
A box. The bigger, the better.
A box cutter or something similar. I like my classic Stanley 199 utility knife. A fresh, sharp blade helps make clean, straight cuts.
Glue or tape. I use Gorilla wood glue, which just happens to be made in the USA.
A pencil, and maybe a ruler (though you can use a cut-off box end as a straightedge like I did).
Paint, if you want.
You could probably get fancier than this and, I don’t know, make curtains or something. I will leave that to you and your therapist to work out.
Building the Playhouse
The steps to build the playhouse are straightforward.
First, secure the flaps on one end of the box. This will be the bottom of the playhouse. If you are starting with a used box, it may already be taped shut, which is fine. Gluing the flaps shut makes the entire structure more secure (which extends the life of the playhouse) and keeps them from flopping about.
If you glue the flaps, give them a few hours to dry. You can “clamp” the flaps together by turning the box bottom side down and placing something heavy like paint cans on them.
Now cut off all four flaps on the other end. This will be the top. I will come back to why I leave the top open in a minute.
If you want to add a roof profile of some sort, this is a good time to cut those bits out. Use your ruler or the edge of a cut-off flap as a straightedge. Learn from my mistakes: do not succumb to the urge to eyeball your cuts. As Norm cautions: “Measure twice, cut once.” It doesn’t need to be perfect, but stupid mistakes lead to frustration, which leads to making this not as much fun as it should be.
This is also a good time to plan for your door. Just cutting an open space is one easy option. One of the cut-off end flaps provides a handy template that is big enough for kids up to probably 5 years.
In previous playhouses I have just cut through the top, bottom, and one side of the door, then made a slight score on the other side of the door as a hinge. This is quick and easy, but the top corner of an unreinforced door tends to bend and collapse over time, particularly if you cut in a window.
For this set of playhouses I glued one of the cut-off flaps onto the side of the box to create a much stronger double-layer door. When the glue dried, I cut a window, cut the three edges, then scored the remaining edge on the inside to create a hinge.
If you have problems with the door, do not despair. A little packing tape cures most problems. Worst case scenario: just cut out the door and go without.
Windows can be cut out either before or after painting. I like to carefully map out the first window, then use the cut-out piece as a template for the other windows. One on each side lets in plenty of air and light. Just be careful of cutting out so much that the box becomes weakened.
To Paint or Not to Paint?
That choice is really up to you. I did not paint our first few attempts and the kids were perfectly happy. Eventually they decorated the boxes themselves with crayons and tempera paints.
This time I had some leftover interior primer — the 5 gallon bucket seemed like such a good idea — and used it as a neutral base. A roller makes this go on fast. Do not apply the paint too thick, though, because the moisture may warp the cardboard. On the other hand, I think the dry paint gives the box a little added rigidity. Your mileage may vary.
Let the paint dry thoroughly in a well-ventilated area. Then, you can add any decoration you like with whatever paint you have around the house. I raided the kids’ tempera paint supplies, mixing colors as needed. (That greenish castle door was an ill-advised attempt to make brown. Should have looked it up, first.) Again, rollers are handy for large areas. Don’t bother putting the paint on too thick. It’s not a Hollywood set, after all.
And that is it. I would like to get some carpet squares to put in the boxes eventually. That is on the roadmap for vNext.
About the Open Top
Earlier I mentioned cutting the top off the box. We did not do this on our first attempt years ago, but here are a few reasons why I do so now:
Ventilation. An enclosed box, even with a few side windows, can get hot and stuffy inside. Plus, some boxes and paints outgas a bit, which can’t be good for the kids. Top off equals cool, fresh air.
Easy access. The open top makes it much, much easier to retrieve toys and children as well as cleaning out any messes.
Safety. We can always see what’s going on with the open top. And if a rambunctious child tips the box over — it happens more often than you would think — the open top allows you to get in or the child to crawl out easily. One enclosed box tipped over on the door will convince you of the wisdom here.
I have tried making A-frame roof structures over the top, leaving the gable ends open, but never figured out a method appropriate in effort to a disposable cardboard playhouse. The kids don’t seem to care, so I haven’t revisited the problem.
Reuse and Recycle
After our last two moves we ended up with, of course, a good selection of large moving boxes from which to build playhouses. The large wardrobe and appliance boxes are best. But not all boxes are created equal.
You don’t want boxes that are too beaten up because they lose structural rigidity pretty quickly.
They also get dirty in transit, and it is not easy to wipe down a box to clean it up. Paint does help trap and hide dirt. Make sure to check the inside of the box for dirt, oils, smelly smells and bugs.
Boxes that have been soggy are poor choices. They are already starting to fall apart and I would not bother. I am also sensitive to mold and mildew, and most boxes that have been in storage for a few months will have picked up some fungus. Again, best to avoid these. You may, however, have better luck in a very dry climate.
For the set shown here we picked up new wardrobe boxes from a nearby big-box home improvement center for about $10 apiece.
Depending on your tolerance for chaos and falling-apart toys, as well as the mayhem created by your lovely children, these boxes will last anywhere from a few weeks to a few months. When the door breaks, cut it off. When a corner rips, tape it up. When the whole thing starts to warp, bend and fall apart, please recycle.
Then build a new one.
I’ve been working with software developers for a long time now, and one thing I learned along the way is that coders are a diverse bunch. That’s one reason why it has been fun and entertaining to launch our A Coder Interview With… series of interviews at the Code Project. We started the series in August 2011 and have been posting a new interview more or less weekly since then.
The big idea behind these interviews is share the stories of working developers who are actively involved in larger coding community — whether that’s the Code Project in particular, open-source projects, or just folks who actively share their knowledge and enthusiasm about programming.
I’d like to acknowledge that The Setup provided much inspiration for this project. I really enjoy the consistent, concise format of these interviews. For Code Project we chose to use a similar set question format, but expand the topic to discuss topics like languages and frameworks of interest, how they learned to program, what advice they’d give to up-and-coming programmers and what they really despise in a codebase.
I heartily recommend reading through these interviews to get a good idea of what tools and techniques working developers are actively using today and the new technologies they’re embracing for tomorrow.
By the way, here are some of our most popular interviews so far:
Chris Maunder, co-founder of The Code Project.
Dave Ward, better known to many of his readers and followers as Encosia.
Sacha Barber, one of The Code Project’s most famous and most prolific members.
John D. Cook of the fascinating blog, The Endeavour.
Phil Haack, former ASP.NET team member, now a Githubber.
There are many other interesting interviews, and we keep adding more. For a taste of the fascinating folks we talk to check out:
Iris Classon, whose 18-month journey from newbie to pro-coder is a true inspiration.
Khaled S. Ali, an actual rocket scientist: he writes the code that controls the Mars rovers.
More are on the way. Stay tuned.
The CSS3 Color Module much more solid than the other CSS3 proposals and experimental features. In fact, as of June 2011, it’s an official W3C Recommendation. New CSS3 Color features include HSL color specifications in addition to traditional hex and RGB values, as well as the ability to use opacity and gradients.
As a primer for using these new color features, I wrote an article over at The Code Project called CSS3 for Beginners: Color and Opacity. This should get you started. If you find the article helpful, please vote it up and share your thoughts in the article comments.
A basic - but often misunderstood - feature of CSS styling is something called the box model, which defines the rectangular space around an element by means of border, margin and padding settings. It’s really very simple, but a combination of poor nomenclature and some subtle rendering rules confuse folks who are new to CSS.
To help you get up to speed with the box model, I wrote an article over at The Code Project called CSS Basics: The Box Model, Margin and Padding. Please check it out and, if you find it helpful, vote it up. I hope you learn something useful.