May 18, 2015
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.
May 14, 2015
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?
- 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.
May 7, 2015
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.
Apr 29, 2015
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.
Apr 8, 2015
Building Static Sites with Node.js and Wintersmith
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.
subscribe via RSS