Tips for Writing for a Tech Audience

I’ve been writing articles and blog posts about web development and technology for a long time. The original version of this blog started in 2004, but by that time I’d already written a couple articles for the ultra-prestigious ColdFusion Developer’s Journal (it’s ok to feel jealous). However, I’ve also been editing articles and blog posts about web development and technology for a while too. It started when I was at Adobe helping to run the Adobe Developer Connection a few years ago and continued when I launched my own site (Flippin’ Awesome which is now Modern Web and not run by me anymore). I still do this on an almost daily basis running the Telerik Developer Network. All of this experience has taught me some things that I think help to make a really good (and potentially really popular) article or blog post for a developer or technology audience. In this post I’ll share my recommendations, though I should note that I’m not an expert at always following my own guidelines all the time. Have a Style It’s important to keep in mind that you aren’t writing API docs. API docs are generally dry, boring and simply stick to the facts. That’s their goal. However, an article or blog post should allow some of your personality to shine through. This helps to make the content both more relatable and more enjoyable to read. Keep in mind that your goal is both to educate and to entertain, to some degree. Some developers revert to a litany of code and explanation. It’s better to have a voice and have a story. Some things that can help: Explain why you are trying to do something, not just what you are trying to do and how you are doing it. What made you get interested in doing this? Did you have a struggles along the way? There’s no shame in admitting that you found something difficult - your readers will likely relate to the experience. Have fun with the demo! Perhaps pick something you are interested in that isn’t technical. For example. I often choose to use some cartoons I enjoy as subject matter for my demos. Know Your Audience While you should have a voice and a style, it’s important to know when it’s ok to be more or less casual in your voice. If I am writing something for my blog, I am often much more casual than if I am writing for the Telerik Developer Network or Sitepoint. If I am writing for my blog, proper grammar, punctuation and spelling are less important. If I am writing for a professional site, these become the difference between seeming like an amateur and not. You’d be surprised how people are affected by these things, even if they do not recognize it themselves. Some sites have editors who help with this, but others don’t - so don’t rely on them to correct your mistakes. Try to always have a friend you trust read through the article first - this isn’t critical for a personal blog post but even those can benefit. Even the best writers need a second opinion and there is nothing than can make your content better than a good, critical opinion. Stay on Track So many developers tend to think that every little detail is pertinent. So, they get sidetracked. Instead of traveling straight down a path, they don’t just point out the detours, but take you down them. As a rule, if the information doesn’t apply to most situations, don’t spend time on it. These are the kind of scenarios like, if you are running an old version of X operating system and want to perform special action Y, you’ll need to do this a different way - let’s walk through it. Another example is getting lost in caveats, detailing every minor exception that in all likelihood doesn’t apply to the reader. The best strategy in these cases is to simply point to the “detour” as an aside and link to the best resource to follow. Or note that there are exceptions but don’t go detailed into the full list of caveats. You may feel as though you are being somehow incomplete in your coverage, but you are less likely to lose the 90% of the readers to whom the straightforward path applies by not catering your post to the 10%. Avoid the Wall of Text There is nothing harder to read than a post that has no headers and is filled with overly long paragraphs. Adding section headers and even subheaders for long sections not only makes your article easier to read, but also makes it easier to scan - which can help the reader determine it’s value to them. Shorter paragraphs also make your content more readable and scannable. Plus, a wall of unbroken text can seem intimidating to a reader. Break up large paragraphs and, whenever possible, place key ideas into lists, which I’ve found can help drive home key points and improve retention. What Are Your Ideas? Hopefully you’ve found these ideas helpful. Do you have any strategies you use to improve your writing? Please share.

Posted by on 18 May 2015 | 4:00 am

Why are Web Developers Hostile to Audio?

I like to talk and write about Web Audio. It can be a fun topic. However, most talks and demos fail to touch on anything useful. Sure, we can build drum machines and sequencers to our heart’s content, but how does this apply to 90% of the web? It doesn’t. Thus, when I speak or write about web audio it seems to draw a niche audience. However, recently I have been on a mission to talk and write about how web developers can use web audio to enhance their applications in practical and useful ways. The frequent response I get is like the one below: You gotta love social media because not only did this person make it clear he never bothered to read the article, but 5 people (which on Google Plus is like everyone) gave it a plus one. However, leaving aside those issues, why are web developers so outright hostile and dismissive to even the suggestion of using audio on the web that they aren’t even willing to discuss it or hear arguments as to how it could be useful? Let’s recap: Audio in game UI equals totally expected; Audio in mobile app UI equals acceptable; Audio in desktop app UI equals legitimate, within reason; Audio in web apps equals ARE YOU INSANE?!?! I have a theory as to why. The Legacy of Years of Misuse I expressed this In the early days of the web, we didn’t have the web audio API. What we had was site’s that got clever and used MIDI or, even worse, had some obnoxious “Hamster Dance” like audio. Then came years of Flash Intros and more useless audio. It became ingrained in web developers’ heads that audio on the web was purely a gimmick. It is such a widely accepted “faux pas” to include audio, that even the mention of carefully considering audio brings strong reactions. It’s Time to Let It Go But do we have to be held back today by the misdeeds of years ago? Sure, the web audio API can be misused. Sure, so far, we’ve mostly shown how it can be used for things like 8 bit video game music (guilty as charged) and web-based drum machines. (Not that those things are useful, even purely as excercises in having some fun with your programming skills, they are beneficial.) The point is, though, this doesn’t negate there being useful and practical ways to integrate audio into your web application. If it’s ok for every other type of application, why not the web? Unlike the commenter above, perhaps you’ll give my full article a read. I’d love to hear your thoughts on the topic.

Posted by on 14 May 2015 | 6:15 am

Jekyll Versus the Competition

On Saturday, May 2, the first ever JekyllConf was held online and featured some really prominent speakers including Tom Preston-Werner and Brandon Mathis. I had the honor of opening the event with my session comparing Jekyll to other popular static site engine options including Harp, Hexo, Wintersmith, Hugo and Middleman. In summary (and in my personal opinion of course), Jekyll is still in the strongest position of all the engines. It has the strongest community (partly evidenced by JekyllConf itself), the best documentation (not saying it couldn’t be better, but it’s better than the alternatives) and has the largest selection of pre-built templates and plugins. However, it has failed to reach much beyond hardcore developers. This is partly because of the nature of the tool - for instance, few people outside of the developer community enjoy working on the command line…in fact, most find it intimidating. Tooling for authors is weak too - Markdown is a terrible option for authors (who aren’t developers). We think of it as being so simple and easy, but that’s actually what makes it so complex. In terms of authoring, it covers a majority of use cases, but it is still very common to encounter requirements that it doesn’t meet (intentionally, since it’s goal was simplicity). Thus, when you teach an author Markdown, you need to teach them the syntax, what it doesn’t cover and HTML to handle those scenarios it doesn’t cover. This is actually more complicated than simply teaching them HTML. In my opinion, until the tooling is available to allow authors and contributors to write using the tooling they love, static site engines will remain a niche solution. This is a shame as they actually seem like the optimal solution for content focused sites and, perhaps more so, documentation sites. The good news is that there are people working on the tools needed to bridge this gap…we’ll see how this goes! You can see the full session recording below or view the full recording of the day here.

Posted by on 7 May 2015 | 6:15 am

Tools for Writing and Converting Markdown

By now, most developers are familiar on some level with Markdown. It’s become a somewhat ubiquitous part of developer tooling, probably in no small part due to it’s usage for documentation in GitHub. It also plays a big part in nearly all the major static site engines. The power of Markdown and probably a significant reason for its success is in its simplicity. But this is also its biggest weakness. Developers love Markdown because it offers a shorthand for probably 80% of their writing use cases - things like blog posts and basic documentation. For the other 20%, developers have no problem switching to straight HTML, which, of course, you can include in a Markdown file without issue. For writers and the general public however, this presents a huge obstacle. They cannot use the tools they are comfortable in writing with and they not only are forced to learn Markdown syntax, but they must learn those cases that Markdown doesn’t cover and the HTML to use in these cases. It’s multiple layers of complexity for the sake of simplicity. That being said, as Markdown becomes more widespread in its use, the tooling around it is slowly improving. I use Markdown daily and below are some of the tools that I’ve found useful in my own experience. Desktop Editors Most code editors such as Brackets or Atom already include some level of Markdown support. However, if you’re looking for an editor with richer functionality geared specifically towards Markdown, then there are a number of options. Mou is my current go to option for writing Markdown. As with pretty much every Markdown editor out there, you write in Markdown and have a live preview available. There is currently no option that I am aware of where you write in rich text and have it converted to Markdown. Mou offers syntax hinting and highlights as well as keyboard shortcuts, but my favorite feature (and why I prefer it) is the export. I rely heavily on the export to HTML feature and, in my experience, it has the most reliable of the editors I have tried. The only quirk I find is that it often stumbles when using backticks for code blocks (and doesn’t recognize the GitHub-flavored Markdown syntax for indicating the type of code within a code block). Currently Mou is still free, though a 1.0 looks to be forthcoming that will be paid. Another free option is Macdown, which was created when Mou appeared to be ceasing development. I found it to be quite buggy, personally, but have not tried it much since its initial release. If you are on Windows, some options I’ve heard recommended include Texts and MarkdownPad, though I have limited experience with either. Lastly, while not technically an editor, Markdown Live is a useful tool for live-previewing Markdown as you write it. Once installed, you simply change directory into the folder you want to serve up and enter mdlive and it will open a preview in the browser that will update as you type - without the need to save the file. This can be useful if you prefer to use a plain text editor for writing Markdown. Web-based Editors If you are looking for a free web-based option, Dillinger is a free (and open source) Markdown editor for the browser. It includes a live preview as well as the ability to import documents from numerous sources and export them to various formats. However, one of the things lacking in both desktop and web-based editors is collaboration. If you are working on a team, the ability to share, comment and collaborate on a document is not just useful, but necessary. Beegit is a commercial offering that includes a number of collaboration features. My team uses it mostly for the ability to share and comment on documents as they are being developed, much as you would within Google Drive. Converters When you are working with a number of contributors, it’s not always possible to force everyone to use Markdown. While Markdown’s simplicity makes it simple to manually convert short documents, converting long documents or groups of documents could get tedious and time consuming. While they aren’t perfect, in these cases, a converter can be enormously helpful. One converter that I rely on frequently is the Word to Markdown web app. Simply choose your local file and hit convert. The site will post you the Markdown it generates from the file as well as a live preview. For good or for bad, it even embeds images in the document using Base64 encoding. Personally, I find this can be difficult to clean up and replace with external images, so I often remove them from the source document first and put placeholders. Word to Markdown is also available as an open source project and command line tool. In my experience, I couldn’t get the command line tool to work properly for some reason, while the web app worked perfectly. In other cases, you may encounter rich text that you need converted to Markdown, such as text copy/pasted from the web or some other editor. In these situations, I’ve found Mark It Down to be both reliable and helpful (it is also open source). Simply paste in the rich text and hit the convert button to get back nice, clean Markdown. Other Tools? This is by no means a comprehensive list of Markdown tools - just the ones that I’ve personally come to rely on at some level or another. Are there any others that you recommend? Be sure to share in the comments as I’m always looking for new ones.

Posted by on 29 April 2015 | 6:15 am

Building Static Sites with Node.js and Wintersmith

When I’ve spoken on the topic or even when I posted my recent guide to getting started with Jekyll, the question I always get is if there is a comparable static site generator to Jekyll that is built with JavaScript and available on npm. The reason people cite is that they aren’t comfortable with Ruby and thus have trouble when they encounter problems with Jekyll or are unable to customize it completely to their needs. Well, there’s good and bad news. First, the bad news… I have found nothing comparable to Jekyll in terms of overall features, documentation and community. Now I don’t know every engine out there, but, so far, there’s nothing that even comes close to fully matching Jekyll. The good news, however, is that I found Wintersmith to be a viable Jekyll replacement. It has a lot of the key features and is extensible. Plus, there are a reasonable amount of extensions out there for it already. On the other hand, the documentation is awful (let’s be honest) and the community is small. So, if you run into a problem, you’re stuck reviewing the source code. On the upside, I found the source code is pretty self-explanatory when I needed to rely on it. Given the lack of a good getting started guide in the Wintersmith documentation, I wrote a two-part series for Sitepoint that walks you through the entire process of building a site. It follows the same exact format of my Jekyll guide covering everything from installation to templating, creating posts, custom metadata and custom data. Getting Started with Wintersmith: A Node.js-based Static Site Generator - Part 1 Creating Posts, Custom Metadata, and Data in Wintersmith - Part 2 The source code for the example is part of my Static Site Samples GitHub project which also includes the aforementioned Jekyll sample as well as examples for Harp and Middleman.

Posted by on 8 April 2015 | 4:00 am

A Guide to Building Static Sites with Jekyll

As I’ve posted about recently, I’ve been speaking a lot about comparing static site engines. There are a ton of options out there (389 as of today, according to this site). However, based on my personal experience, I always recommend Jekyll - granted, that’s based on having used 5 of the 389 so far. I already have a GitHub project where I have built the same project multiple times with different engines as a means of comparison. The readme will guide you with installing and running each of these should you choose. Now, if you wanted to learn how to use Jekyll using this sample, I have written a detailed guide to getting started with Jekyll for the Telerik Developer Network. It walks through the most common things you need to know about Liquid templating as well as how to create and build your Jekyll site. I hope you enjoy it! P.S. One common questions I get whenever I recommend Jekyll is from people who don’t know Ruby and would prefer a solution written in JavaScript/Node.js and, preferably, available via npm. The GitHub project includes two, Harp and Wintersmith. I have a follow up article that should be published any day now that walks through the same steps laid out in the Jekyll tutorial, but for Wintersmith. I’ll post about that as soon as it is out.

Posted by on 24 March 2015 | 4:00 am

Can Web Audio be Useful?

Next month, I will be presenting at the Fluent Conference in San Francisco on the topic of “Practical Web Audio.” The idea here is that most every demo or presentation about web audio (including my own) have been fun and cool but not practical unless you build games or music software. So, are there useful purposes for web audio in a standard web app? I wrote an article called Adding Audio to Web Apps that begins to explore some ideas. In almost every case, the demo uses very brief portions of audio to try to add context to some form of input. Notifications seemed obvious - but, admittedly, others are harder to make a strong case for except in very specific circumstances. These were just some of my initial ideas - I have a few others and some variations to the ones I showed already that I am working on. Have you used web audio in your web app for something useful? If so, please share (and maybe I can even show it at Fluent).

Posted by on 14 March 2015 | 4:00 am

Comparing Static Site Engines

On February 18, I had the pleasure of gaving a talk to the San Francisco HTML5 User Group. The topic was static site engines, covering the basics of what they are and what they are good for (or what they are not good for). The latter half of the session focused on comparing three popular static site engines: Jekyll, Middleman and Harp. You can view the presentation below (I am also giving an updated version of this presentation at DevNexus in Atlanta later this month). Sample Application In order to compare the engines, I created a simple sample site, using data from the Adventure Time Wiki. The site is intentionally simple, but uses things like custom post attributes, custom global attributes, data and, of course, posts. You can get the samples as well as the slide deck on GitHub. I am hoping to add additional samples in the coming weeks. Recording

Posted by on 4 March 2015 | 3:00 am

Patterns of Development

Patterns are something that you cannot view close up - a narrow view obscures the pattern. However, given distance and time, we can begin to make out the sequences that repeat. This is one of the few benefits of being old, which I am compared to many developers. In this post, I am not talking about development patterns as in software design patterns (or anti-patterns), but rather patterns in attitudes and behavior among developers that change the way a large number of us approach our work. Front to Back to Front to… I want to discuss a pattern I have noticed throughout my career and has only become more obvious over time. This pattern is the constant shifting in focus from front-end heavy applications to back-end heavy applications. I’m bringing the topic up becuase I believe we’re seeing a shift again, which becomes clear in recent controversies over AngularJS. Basically the pattern is that every 5 to 10 years (or so), developers seem to shift in attitude and opinion on where to place much of the burden of the application - moving from placing much of the application and business logic on the front-end, to placing it on the back-end. I think a little history might make this pattern seem clear (though you can feel free to disagree with me). Back in My Day… As an old person, let me give a very oversimplified history. So, I’m not that old - really I am not. But even when I went to college it was still fairly common for many applications, especially in the enterprise, to simply be a lightweight terminal-type interface to a mainframe that had the power to run the actual application logic. In this case, obviously, the “front-end” application was little more than a text entry interface for entering commands into and receiving data back from the mainframe (which was effectively the server in this case). Rich Client Server Desktops Applications As PC’s became more powerful, development tools (PowerBuilder was a popular one) helped developers create more complex and interactive native applications for the desktop. While the back-end might retain a good chunk of logic, the interface itself contained a lot of interactivity and the flow of the application was based upon certain business rules. Basically, many aspects that previously had to be kept on the back-end could now be pushed to the front. Early Web Applications The rise of the web changed this. Why? Well, the early web was slow and limiting in many ways. It was powerful in the sense that I no longer needed to deploy applications across multiple desktops, make sure they were updated and so on. It allowed us to interact with our applications from anywhere. However, the capabilities of the browser meant that our applications were closer to the dumb terminals of earlier days than the rich applications on the desktop. Sure, they may have looked pretty with forms and tables and blinking text, but they were mostly dumb - the application logic residing almost entirely on the server. Flash, Flex, Silverlight… This didn’t change because browsers improved - at least not initially. Plugins like Flash built upon the initial attempts (like Java Applets) to give browsers the ability to create rich, desktop-like experiences on the web. Soon Flex and Silverlight were hot and much of the application and even business logic was moving back onto the client. Sure, we had to build portions of our business logic and validation twice, but the experience for the user was much improved. We called these Rich Internet Applications in part to recognize them as an attempt to recreate the interactivity of desktop applications but served in the browser. HTML5 This focus on the front-end didn’t change with the death of Flash and the growth of HTML5. Actually, if anything, it increased. The primary difference was that now we were writing complex, desktop-like applications in JavaScript rather than ActionScript. In fact, many back-ends became so lightweight that, in many cases, applications would connect directly to data on the cloud or in NoSQL databases. A Shift (imo) I actually wondered if we might be hitting a point where this pattern would break, but a couple of things changed as I see it. First, there’s the rise of JavaScript on the back-end using things like Node.js (or io.js if you now prefer). This isn’t because JavaScript is so awesome, but because it allowed us to write business logic and validation and such in one language and it could run on both ends - meaning, for example, I don’t have to write data validation in JavaScript on the front-end and Java (or PHP or whatever) on the back. Also, these servers are fast and built for running the types of web applications people seem to be building today. However, that isn’t the big reason. The major shift is because of mobile (of course!). As you may have seen in some of the recent AngularJS debates (among other related topics), placing too much burden for processing and logic on the front-end can make an application run poorly on mobile. And nevermind writing things like writing validation rules twice, we certainly don’t want to have to write our applications once for the desktop and then for each mobile platform. Thus, we need to move some of the code that we’d perhaps become accustomed to placing on the client back onto our back-end server…and so goes the cycle. Now, perhaps this trend will cease. Mobile devices are rapidly becoming very powerful computers in their own right. Or perhaps I am old and my mind is causing me to see patterns that don’t exist. But given the back and forth on this that I have witnessed over my career, I suspect we may be in the midst of yet another shift.

Posted by on 21 January 2015 | 3:00 am

The Content Model of the Web is Broken

Print is dead. This is one of those supposed truisms we’re all lead to believe. It may or may not actually be true, but if print isn’t dead, it’s not healthy. This is especially true when it comes to news and information. Magazines and newspapers are failing all over the place. However, what you may not realize is that this same type of information is dying on the web as well. Sites are disappearing and the ones that aren’t, in large part, don’t make money off their content. Basically, as of right now, the content model of the web is thoroughly broken, and you are paying the price. In this post, I’ll speak mostly about sites that focus on content around technology and development, but I think much of this could apply to most any topic area. Keep in mind this is, obviously, all just my personal opinion and some of the information is based on speculation about certain business models. The Symptoms Some popular developer and technology sites have begun to close such as Dr. Dobb’s and The H, to name a couple of recent ones. While these may not seem like horrible losses, I think they are essentially the canary in the coal mine. In fact, other sites you may care about more, such as MacWorld, InfoQ (run by C4Media) and SD Times (run by BZ Media) have also had to adjust their online businesses to adjust to changing times. These are just a few examples, and by no means a comprehensive list. What changed? There’s simply no money in advertising for content sites. Ad networks, most notably Google, don’t pay what they once did. Direct advertising dollars are now very hard to come by. I used to run a site called Flippin’ Awesome (now called Modern Web), and I can tell you first-hand that the amount of money available for ads was paltry - especially when placed against the amount of space they occupy (and the nuisance they are). Sure, I only got a couple hundred thousand page views a month, but that netted me generally less than $300/mo. Once you factor in the costs of hosting/running the site, plus my time, this was not a profitable venture by any means. The Three Types of Surviving Sites Of course, many sites still survive, but mostly because of trade offs that you may or may not be aware of. 1. No Longer Really About Written Content Many sites survive because their content is really simply a means of promoting their actual revenue generating side of the business. For example, sites like Smashing Magazine, A List Apart and InfoQ (to name a few off the top of my head), primarily serve as promotional vehicles for their conferences, which make money (I know no financial details - I’m purely speculating). While this doesn’t mean that their content isn’t still for the most part very good, it does mean that it isn’t the driving force of their business. This can mean they cut down on publishing, cut down on paying writers, cut down on other things (editorial, technical editing) or some combination of all three. In the end, however, if you’re site is just promotion expense for some other part of the business, cutting either quality or quantity helps keep the costs manageable. 2. Corporate Sponsored I have some experience in this area as I used to run part of the Adobe Developer Connection (ADC) and now run the Telerik Developer Network. This type of site is similar to the first in that its primary purpose is actually as a promotional vehicle for something else - in this case, to sell you the products and/or services of the company that runs it. This also doesn’t mean the content is bad. In fact, these types of sites often have the budget to properly compensate authors (or compensate them at all). Paying authors makes it easier to get good authors. Nonetheless, these sites have a clear cut agenda which is to benefit the company footing the bill (that makes sense - it’s not a criticism). The content is only as independent as the company behind it chooses (I’ve been lucky in this sense to have always had freedom). In addition, the site is at the whims of the company - thus, one day the ADC was growing and healthy, the next day it was effectively dead. Running these sorts of sites is not cheap and its impact on sales is tenuous to track (I think they are important, but it can be hard to find a direct link to actual sales). 3. They Rely on Free Content This type of site doesn’t always even exist to be profitable would include most blogs but also sites like my old site (at least when I ran it) and even sites like Huffington Post, who often rely on free or reprinted content, especially outside their main areas. The problem with free content is that it isn’t always the best quality. I spent a lot of time working on articles and with authors to make sure the content on Flippin’ Awesome was worthy of printing. I also had to reject countless submissions, many of which were the article equivalent of spam. Many sites don’t have the time, money or interest to do this. Other sites, like most blogs, rely on the generosity of their authors. However, this means that a) their’s usually no one reviewing what they wite and b) it’s rarely a top priority, and often die. We’ve Thoroughly Devalued Content and Writers I hate to say it, but the reason behind all this is that we, the consumers, want our content to be free. Not only that, we also think it should be free of obnoxious ads. This means that, even the sites of types 1 and 2 above, pay authors crap. Let’s be honest, no author is making a living on writing articles at $200-300 a pop (which is more or less the going rate). Sure, it’s better than nothing, but other motivations have to come into play. Personally, I worry that this model is only going to further deteriorate. If you want to make money on content given the money there is on advertising, you either have to produce gobs of content (and raise your page views based on volume) or you use link-bait (and raise your page views based on trickery). Often, it is a combination of both. In either case, the quality is what suffers and you pay the price. So the next time you do a Google search and the top 10 articles are filled with link-bait junk written by content farms, just think that this may only get worse.

Posted by on 16 January 2015 | 3:00 am