Ollomedia

As I’ve worked with several different teams over the years I’ve found documentation to be a bit of a hot button topic. Some feel over documentation is the only way to professionally deliver work and some prefer to simply write “self-documenting” code. I’ve sat through multiple debates and have been part to many a code review where these two mindsets have caused quite a stir.

Premise

On a recent fairly large application build I decided to test some theories around documentation with Sass. I wanted to attempt a documentation driven approach which I define as:

All code that is intended for re-use or extensibility within a library or project should have documentation written up-front or in parallel instead of it being added after the fact.

This may at first just appear to be a pedantic argument, but I wanted to research and possibly prove a couple of hypotheses through this approach.

1.) The project at the end wouldn’t lack documentation like so many other great projects do and if the documentation efforts had fallen behind it would be less effort to back fill.

2.) Code quality would increase as there was more thought put into the solution at the time of authorship.

In my opinion CSS is a fairly simple language with a long history of hacks. I find its very easy and far to common to just write more code rather than think through problems up front and write well thought out modular solutions. Also documentation as a practice is pretty rare in CSS as a whole unless you are viewing the source for a popular public framework or library.

Risks

Alongside these hopeful outcomes I also theorized a couple potential side-effects of taking this approach.

1.) Developers velocity would decrease as more thought would be needed during authoring and this might disrupt a typical workflow.

2.) Code bloat. I wondered if writing docs upfront would influence a developer into thinking every line of CSS has to be modular and re-usable.

I feel these risks have to be weighted differently depending on the project. In my test case above, we had plenty of runway to work through some early prototypes and think of systems to use in our css. These fairly complex systems necessitated a comprehensive set of accompanying documentation that other engineers could ingest for feature development. If I had a smaller site or project I doubt I would take such a stern approach to being document driven.

Tools

KSS is the tool I decided to use for documentation. It had some notable use cases and pretty decent documentation even if it only provided ruby references. I also utilized a gulp plugin to automate this step into our existing build pipeline. We also created our own theme for our documentation and incorporated angular and google material as both of those libraries are used in the project and they were needed as dependencies in order to properly represent our apps components.

Conclusion

If I told you this experiment went off without a hitch I would be lying. We did end up having a much larger and more comprehensive set of documentation, but when deadlines loomed we loosened our convictions to maintain them. We ended up having to backfill documentation and do several rounds of refactoring to get our Sass components and docs up to date after major deadline pushes with new feature development. The documentation did however prove to be a useful resource to more team members that were more focused on data and application development with less focus on UI. Overall I feel that for this strategy to be successful it needs to be established as a core principle for each team and there really needs to be buy in from the whole team to ensure success.

So for the past few months I have been using Sass for all of my projects. I’ve been using Bourbon and Bourbon Neat as part of my workflow but recently have been working to implement rem measurements for my typography to assist in font scaling for responsive builds. This was a bit daunting at first after I read about the calculation for rems as I was already used to being spoiled by Bourbon’s em() function so I whipped up a function to do the conversion for me.

// calculate rem based on a pixel value
@function rem($value, $fontbase: 10) {
  @return($value / $fontbase) * 1.0rem;
}

.rem_test {
  font-size: rem(40); // 40px == 4rem
}

Hope you find this helpful.

So if you haven’t jumped into bootstrap to speed up front end development or at least explored it you need to, and hopefully this writeup taken from some of my successes and failures will help jumpstart you into using it effectively as
a front end scaffold.

First we need to understand that Bootstrap is a framework..

One of my first mistakes was in not really understanding what this means and customizing its core directly. This mistake has caused numerous problems like being stuck with an older version and working way harder to override its css output :(

After the first couple of projects I found that the only way to use it effectively is to build off of it and not customize its core files directly. This concept is similar to other platforms and libraries I use { jQuery or WordPress } but it didn’t occur to me immediately since it was a front end framework and the early documentation guided users to work off of the variables to customize it. This caused me plenty of problems until I found the below approach.

Setup

Download the full source from Github { the LESS version }

https://github.com/twitter/bootstrap This is the full core of the framework. It will take some learning if your not already using LESS but it shows how the features are truly built. If you haven’t already viewed bootstrap like this take some time and examine the files and learn which features are created through each file, there are quite a few and learning where they are defined will help later when you want to build off of them or over-ride their look and feel.

Get the right tools

I use a compiler which took some time to getting used to as a front end guy who’s previous experience with compilers was Dev C++ in an intro CS class. I’ve come to find with a little flexibility in my workflow it speeds things up and can help with debugging as I’m adapting to using LESS instead of just CSS. I currently use CodeKit which offers some cool js and framework support. It is a paid app so if your just getting started you might want to try some of the free options { LESS for Mac, WinLess ( ironic ), Simpless, or Crunch. }

Set up your development project

Recently at WordCamp here in St. Louis I discussed theme development best practices and one of the concepts I covered was abstraction. The concept holds true in the method I use to work with bootstrap which I find to work really well. I start with a basic project folder for the site name or project I’m working on and create the basic folder structure for the types of files I will be using. I also add a folder called bootstrap to contain the frameworks less files.

Now I copy over the files from bootstrap that I downloaded from Github into the appropriate directories minus the tests folders that were used in development. Now I have a clean folder structure with some basic assets to start using on my project.

Getting started

Now that you have a basic site structure lets set up our compiler with some resources and instructions on how to produce our styles. First inside of our less folder lets create some .less files to tell the compiler what we are working with. I start with a

• style.less { the master file },
• layout.less { general layout },
• theme.less { colors, buttons, etc }
• typography.less { for headings and type faces }
• misc.less for mixins and utility classes.

Once these files are created open your style.less file and add the following lines.

/* my new bootstrap site */

@import "../bootstrap/bootstrap.less";
@import "../bootstrap/responsive.less";

// import your unique less files as you build

@import "layout.less";
@import "theme.less";
@import "typography.less";
@import "misc.less"  // mixins etc

Once you have created these files and this structure you can open your compiler of choice and add your new project. In CodeKit you simply click the (+) plus sign and browse for your site folder. Once you have chosen this lets modify the compiler behavior.

Basically we want to make sure it is detecting the import statements and that it is only compiling the single style.less file. Also if it doesn’t automatically set the output path for the compiled css you will want to right click and tell it to use /css/style.css. Now we can get started on building our new site with less and the power of bootstrap so if your not already confused read on.

File Strategy

I mentioned before that one of the key things I’ve learned as a developer is abstraction. This concept is constantly at the back of my mind when I’m working on a project because I find its the best way to build readable clean code that someone else may have to work on down the road after I’m finished working on a project. When I set up my less folder with those basic files in the previous step its just a starting point. As I get further into a site I will create several more less files and import them into the style.less file so they are compiled into the final css. This maintains clean easy pieces in my code that are easy to digest.

I also heavily comment using less comments // as they don’t end up in the css and are a courteous way to document my train of thought as I’m working on a layout.

The key thing is to not be afraid of files.

With this method and less they are compiled into one css file so your not adding a bunch of extra http calls and damaging your sites load time by keeping everything broken out and readable. You can even take optimization a step further when your ready to put your site into production and only import the bootstrap files that actually pertain to your design.

Wait.. what ?

Yes. If you open the bootstrap.less file from the framework you’ll see they are doing the same thing with import statements so you can lower the end size of your css file by only pulling what you need!

Closing

This has taken a couple of months for me to refine and get comfortable with but now I’m finally starting to see the benefits as I work with a team of developers on larger projects. This organization lets us minimize development time and makes our code easier to understand without lots of instruction and I hope it helps you on your development projects in the future. If you see improvements that can be made I’d love to hear your feedback or findings while you experiment.

Happy coding.

So I just launched my new WordPress theme. This was more playing catch up than a marketing tactic. I have been working with WordPress for almost five years now but have been so busy with client work and freelance projects that I had left my site to rot.

I regrettably was using a theme I tweaked from twenty ten which was clean but didn’t really capture my style or current WordPress theming capabilities. I also have until recently gotten way behind in my writing activities so rebuilding is a good way for me to get involved in my site and the fun in having a WordPress site.

The latest theme is built from scratch using twitter bootstrap and some tweaks I have learned along the way. There is still plenty of things I want to polish on the theme, but I think some of these initial development discoveries deserve consideration if you are building your own WordPress themes.

Tools I’ve recently adopted

Beyond my standard tools { textmate, terminal and a browser } I started working with a couple of new tools in my development workflow.

The Less App for Mac

This is a simple app but when handling several less files from a framework like bootstrap it takes a lot out of the guesswork and helps get a solid workflow. Some less knowledge is needed but after this theme and several of the latest ones at work I’ve found this language speeds up css development considerably and is well worth the effort to explore.

The developer also has another project some of my co-workers and I are testing right now called code-kit which also looks very promising

Twitter Bootstrap

Yes… I know lots of very important well known developers have already talked about this framework. I admittedly have been looking it over for a year and just now am really learning how to use it to speed up my projects and simplify my development workflow.

If you haven’t reviewed this yet, I can’t recommend it enough and I hope to have many more posts in the future discussing techniques to customize it and use it for project specific functionality.

Github

Yes I know this is old news. Yes I know you are probably way cooler and nerdier than me and have been using this for years. I first learned about github and WordCamp two years ago and now finally understand why it is so important. At Integrity we now use git daily to manage all of our development projects. This is an amazing tool and when working in a team setting it makes collaboration more efficient. The secret to using this in my opinion is branching and I plan to write another post soon on my git workflow for WordPress theming.

Search Wordpress.org Codex

Lastly I use an awesome but simple chrome extension that I use constantly for instant access to the WordPress Codex. When I learned PHP the first think I learned was how to search php.net for functions and documentation so that approach has guided all that I have researched and learned about developing with WordPress. This extension allows me to just open a tab and type “wp” + space + “function, term, or keyword” and immediately jump to the source for documentation. I recommend this extension to all of our new developers and hope you too can find it useful.

If you’ve used one of these tools and think their awesome or think they are sub par to a solution you have found let me know via a comment. I’ll be writing again soon time permitting on some of the workflows I’ve developed with these tools and any new finds. Thanks for reading.

So thanks to my awesome boss Ed @ Integrity I was recommended, and will be giving a chat with my rad comrade Arod this year at WordCamp in St. Louis.

We’re planning a chat for developers that focuses on how to architect a really awesome WordPress theme. Our focus is on how using custom post types, custom meta boxes, and admin customizations can make WordPress a true CMS and easy for clients to learn.

I’m posting the slides on a new service I found created by the guys at Github called Speaker Deck. I like the so far and its simple. It creates your presentation in by uploading a pdf, this makes prep minimal and I get to avoid powerpoint.

Arod and I still have plenty of prep to do but we’re super excited. This will be the first year we have presented and my third WordCamp to attend.

Check back for a follow up post on the details of the event and links to the slides from our chat

UPDATE

Arod and I had a great session that was standing room only! We totally enjoyed the experience and had some really encouraging feedback.

Here are the slides from the presentation for all those interested

Developing online stores while attempting to optimize for conversion is a breeding ground for invention and progression. One issue several store owners are guilty of is over loading their shopping cart with walls of text regarding policies, shipping rules, and (hopefully) clear contact information. While this is all relevant information, visual appeal is the key to converting visitors into customers. One solution I have developed is a simple ‘show/hide’ script written in jQuery that provides a header sentence that is hidden until clicked upon expanding your policy information. Use this to clean up your latest shopping cart enhancements and enjoy the benefit of reduced cart abandonment.

<style type="text/css">
.msg_wrap {
  margin: 2em;
}
.msg_body {
  display: none;
  padding: 1em 0;
}
</style>

<script type="text/javascript">
$(document).ready(function() {
    $('.msg_toggle').click(function(e) {
        e.preventDefault();
        $(this).next('.msg_body').slideToggle();
    });
});
</script>

<div class="msg_wrap">
  <a href="#" class="msg_toggle"> (click to read more) </a>
  <div class="msg_body">
      I'm text that is hidden until the header is is clicked.
  </div>
</div>

I myself use this implementation frequently if information is needed in the cart but space is limited. A word of caution; do not to let this idea enable over saturation of content and information. Customers want the basic information and quick shout-outs on topics like returns, warranties, and contact information. Links to these pages such as Policy and Shipping can give your customers the choice of reading your agreements or ignoring them to keep checking out. You do not want to freak a customer out by providing a ridiculous amount of information and policy that may in turn cause them to shop elsewhere like Amazon or Overstock. Just my two cents here, but this has been a proven tactic to help drive sales for store owners.

As a fellow open source enthusiast and web developer, Josh has been kind enough to invite me to guest post on one of my favorite topics: Linux-based web development. I specialize in the development end and less on design, so bear that in mind, though I’ll also introduce some graphic design tools as well. While the linux platform still lacks a native port for Adobe CreativeSuite, to the chagrine of Linux-loving web developers everywhere, there are still plenty of stunningly useful tools for web developers working on Linux. Before I get to a summary of my favorite of these tools though, I’d like to take a second to talk about the importance of open source in the web industry.

As web developers, we benefit immensely from the richness of the open source community, from the profligate offerings for code libraries for front-end development (YUI, MooTools, jQuery), the scripting languages we love (PHP, JavaScript, Python, HTML, XHTML), the very platform that powers most of our servers (Linux, Unix, BSD), to the servers that offer up our creations for consumption (Apache, Nginx, Lighttpd, Tomcat).

Without the generous contribution of labor and creative product by the multitude of developers working on this great software, the modern web might have a very different face; it’s very difficult to imagine that without the multitude of freely available solutions, the web would be as accessible as it is today.

My heartfelt thanks goes out to the people who make this possible, including the corporations that stand behind open source, putting their money where their mouths are in paying for open source developers and defending open source licensing in the courts. With that said, let’s look at some of the open source tools for facilitating the web development workflow on the Linux desktop.

Graphics

Gimp

An ever-popular, multi-platform image editing tool, Gimp offers a host of tools useful to web developers. Aside from the obvious utility in graphic design for logos, buttons, icons, etc. Gimp also offers tools for splicing an image into pieces and generating table code for layout. This obviously pairs well with web design, as a website layout can be designed as a single graphic, then sliced into it’s composite parts. Gimp also has a handy feature for optimizing images for the web, reducing file-size and improving load-times. With Gimp’s plugin architecture, there are many additional ways to expand the basic capabilities to fit Gimp into your work-flow.

Agave

This simple, lightweight application for the GNOME desktop offers web developers a simple way to generate complementary colors for website elements, offering color pairs, triads, tetrads, etc. with on-demand color-matching and saturation/tone adjustments. It very conveniently provides the corresponding color codes in several formats (RGB/Hex), and the ability to save a list of your favorite color-schemes.

Synfig

This remarkably powerful 2d animation studio is built from the ground up to offer industry quality animation capabilities in a convenient way. Developed by an industry professional who was tired of working with inferior tools, Synfig offers the best flash development capabilities found anywhere, native to Linux. Though I personally avoid flash wherever possible, it remains a reality for web developers, and Synfig more than adequately fills the need.

Inkscape

An incredibly popular tool for vector graphics, Inkscape offers full-featured vector design and editing capabilities, and works very well for designing flexible website layouts that export well for optimization and post-processing in Gimp.

Coding

Every developer’s idea of a useful coding environment differ based on purpose, experience and need. Some prefer the no-bull text-edit mode of vim, emacs, gedit, or kate, some may prefer a fully gui editor like Kompozer, and most probably fall somewhere in between, I’ll give a brief overview of one or two tools for each preference below.

Kompozer

A long time favorite, Kompozer is a simple-to-use web editor that offers a fully graphical development environment with great support for css based templates, great built in code libraries and fully standards compliant code generation. With easy switching between graphical and source-view, this web development software is an understandable favorite for many beginning web developers and a trusted familiar for experienced developers.

Key features: _gui and source editing, built in code support and easy css template generation, built-in ftp client.

Bluefish

My personal favorite development tool, Bluefish has the perfect mix of useful development tools and configurability in a lightweight gtk+ interface. With auto-completion of html, php, and css tags/attributes, a ready css template generator, configurable syntax highlighting, find and replace functionality, it offers all the frills for the text-friendly web developer. To cap off this handbag of win, Bluefish offers a best-of-class image insertion dialog, with automatic thumbnail generation and automatic linking of the thumbnail with the original image, making gallery generation a cinch.

Key Features: tag auto-completion, configurable syntax highlighting, css template generation dialog, automatic thumb-nailing, complete php reference guide

Quanta Plus

One of the best interfaces and offering reliable stability (everyone hates a crash that causes the loss of hours of work), Quanta Plus is a very nice development environment, with a fully graphical, fully code, and split-view development interface, so that you can watch your code unfold as you lay it down.

This tool is very useful, but there are a couple of downsides. First: being developed strictly for the KDE environment, Quanta drags in a ton of KDE dependencies when installed on the GNOME desktop. If you use KDE anyways, this is clearly not a problem, but as GNOME has the majority of installs, for most Linux users, Quanta may not be worth the extra libraries and more frequent updates for software you only use for one application.

Second: Quanta development seems to have come to a standstill, with the last stable version released in 2007. This is disappointing, as the developers produced a high quality application that I for one would have liked to see continue to evolve.

Key Features: syntax highlighting, Graphical/Source split-view, support for css generation, project management, multi-language support, easy web template management across and within projects

Honorable Mentions: Though I’m fond of the above applications for their ease of use and excellent feature sets, many developers prefer other applications, and two that have quite enthusiastic user bases are Screem and Geany. If none of the above strikes your fancy, these may be what you’re looking for. :)

Integrated Development Environments

IDE’s offer a variety of advantages to web developers, aiming to provide all the tools necessary for web development in a central application. Common features are project management, multi-language support, in-application publishing, debugging and revision control. Though there are many IDE’s for many different programming purposes in Linux, I’ll merely list a couple of the larger, more feature-rich applications.

Aptana

Probably my favorite IDE when I am in the mood for a feature-rich, java-script aware environment, Aptana, based on Eclipse, packs a lot of features into a convenient, fast application for web development. Probably the best feature in Aptana is the large collection of importable plugins that let the developer add support for all kinds of projects. By far the most generally useful plugins are the code libraries, including jQuery, YUI, Mootools, Prototype and many more. For each library, code assistance, sample projects and documentation is brought directly into the application. Another big feature is the built-in JavaScript debugging utility. The Aptana team is working on Aptana 3, which will feature git support!

Komodo

The first IDE that ever managed to hold my attention, Komodo is absolutely fantastic for PHP developers, offering excellent syntax assistance, code history (fwd/backwd movement through code), and best-in-class code repository management. It includes the ability to checkout code from central repositories directly within the IDE, and built in support for all of the major revision control systems (git, bzr, mercurial(hg)). Komodo also features an extensively configurable interface, with support for multiple, paned top-level windows for simultaneous review and editing of multiple files. As someone who primarily works in PHP, Komodo is the most useful application for most of my work-flow.

Crash/Performance Testing

Every developer knows that sometimes, despite your most thorough review, bugs can crop up when a site goes live, and it’s critically important to be able to test an application before it’s put into production. For HTML, CSS and simple JavaScript projects, testing can be done readily within the browser by previewing local files, but if you plan to use any PHP, Perl, or Python in your application, you simply can’t presume that the functional bits of code will behave as you expect without putting them through rigorous testing.

To that end, Linux easily outshines other development platforms, especially in the popular combination of tools known as a LAMP server. If you’re not already familiar with the term, LAMP stands for Linux, Apache, MySQL, PHP, who, when the power of their rings unites, provides a powerful, stable, and flexible platform for almost all web-development needs, including a highly stable, configurable OS with low overhead, to get the best performance out of the available hardware, a powerful, secure and extensible web server, MySQL for database needs, and PHP for dynamic scripting, file uploads/downloads, and database interaction.

The tremendous news to Linux using web developers, is that you’re already using the base of this killer combination. Every major distribution provides a simple-to-install binary package for Apache, MySQL and PHP which will typically be configured to run right out of the box. Many distributions even provide a metapackage to install the LAMP package as a whole without seeking out the individual binaries. While the availability of Apache for easy installation is terrific, if you happen to develop on older hardware, a netbook, or would just rather not add another service to your desktop, the XAMPP project is a terrific solution for pre-configured, fully featured testing environment for web developers which includes Apache, MySQL, PHP and Perl as well as several demo projects to demonstrate various functionalities, and phpMyAdmin for a friendly database interface if you’re not comfortable at the command line.

Conclusion

The Linux desktop truly offers a broad variety of options for web developers who may be tired of keeping around a dual boot for a smattering of tools with no familiar counterparts on their desktop of choice. I hope to have introduced here a collection of tools that will help other web developers to make the leap to a fully open source development environment, with no loss of critical features, and minimal workflow adjustment.

Though it would have been impossible to review all of the possible applications for web development available on Linux, if I left out something you consider critical to your workflow, please let us know in the comments, we’d love to hear about your favorite web-dev workflow applications. Did we leave out a particular part of your workflow? Still not sure what may be available to meet a particular development need? Feel free to ask, we’ll be glad to try to help!