Robby on Rails: Tag process

What was that idea again?

Robby Russell — Thu, 02 Aug 2007 08:50:00 -0500

While engaging in another one of our deep philosophical conversations in #caboose, the topic of remembering that great idea that we had before we fell asleep or at any point during the evening.

Manfred Stienstra writes, “I always think of stuff right before I fall asleep and can’t remember them when I wake up.”

This happens to me as well, just not as much as it used to. I keep a small moleskin notebook and a pen on my bed side table and try to get everything in there as it comes up. When I open it, I see notes that don’t make any sense, which were probably after waking up from some bizarre dream. There are many business and development ideas that come up, but it’s often hard to record everything.

I’m sure that there are others who’ve faced this problem. Have you come up with a working solution? If so, would you mind sharing it?

Designers, Developers, and the x_ Factor

Robby Russell — Wed, 01 Aug 2007 00:39:00 -0500

Our team is lucky enough to be in a position where we have both designers AND developers working on the same code base in parallel.

Since Ruby on Rails adopts the Model-View-Control pattern for separating business logic from the presentation layer, we’re able to give our designers a lot of breathing room to to design the interface, whether it’s for interaction or aesthetic reasons. However, sometimes this breathing room has resulted in small bugs slipping into the application interface. In general, nothing disastrous, but each bug that slips into the queue, slows down the project and we want to avoid as much of that as possible.

I’d like to share a few issues that we’ve seen occur on various occasions, and then show you what we’ve done to avoid them happening again.

Scenario #1: The case of the changed div id, (victim: designer)

Designer adds a few HTML elements to the page, defines an id on a <div> tag and styles it with CSS.
A few days later, a developer needs to make some changes, tests it in their favorite browser and commits.
Later, the designer doesn’t understand why the styling is all messed up. “It was working fine.”
...minutes, hours… go by where the designer tries to track down the issue. “Oh! Someone renamed the id in this <div> tag. Sigh.”
Developer apologies, but explains that he needed to do it because he needed to make it work with his new RJS code.

Scenario #2: The case of the changed div id, (victim: developer)

Developer is implementing this cool new Ajax feature into the web application
- The code relies on there being one or many HTML elements in the DOM with specific id values defined.

Example: <div id="notification_message">

A few days later, a designer is making some changes to the layout and needs to restyle some of the view that this <div> tag is defined. Designer decides to change the id to a different value for any variety of reasons. (or perhaps they changed it to use a class instead of styling it by the id). Often times, we don’t know who set the id or class… and many times the developers aren’t savvy enough with HTML and designers end up cleaning things up a bit.
Later, code is checked in and designer didn’t notice that the Ajax was now breaking as they weren’t focusing on just the layout.
Day or two later, developer sees bug, “Feature X isn’t working, throwing JavaScript error…”
Developer is confused, “Hey, that was working! What happened?”
Developer tracks down the problem, discusses with designer, they figure out a solution. Problem solved.

I could outline a few other examples, but I really wanted to highlight these two types of situations, as our team has seen this happen on several occasions. Luckily, we’ve learned through these experiences and have taken some measures to try and avoid them in the future.

Moving forward (together)

Both of the examples above, were essentially the same problem, but resulted in problems for a different role in the design and development cycle. While, I’ve definitely been the victim of #2 several times myself, I know that I’ve also been the guilty of #1. So, what can we do as designers and developers to work with each other without causing these little problems from occurring? (remember: many little problems can add up to a lot of wasted time spent resolving them)

Several months ago, I had a meeting with Chris (User Interface Designer) and Graeme (Lead Architect/Developer) to discuss this very problem. At the time, we were implementing a lot of Ajax into an application and were occasionally running into Scenario #2. We discussed a few possible ways of communicating that, “yes, this div id should NOT be changed (without talking to a developer first)!”

Idea 1: Comment our “special” HTML elements

We discussed using ERb comments in our views to do something like the following.


  <% # no seriously, please don't change this id, it's needed for some Ajax stuff %>
  <div id="notification_message">
    ...

We all agreed that, while effective, it was going to clutter up our RHTML code more than any of us desired.

Team Response: Meh.

Idea 2: Reserve id’s for developers

Another idea that came up, was to ask that designers only use classes and ids wold be used by the developers when they needed it.


  <div id="developer_terriroty" class="designer_territory">
    ...

Chris pointed out that this wasn’t an ideal solution as there is a distinct case for when to use ids versus classes.. and he is very strict about adhering to the HTML/CSS standards.

Team Response: Not hot about it…

Idea 3: Naming convention for Ajax-dependent elements

The third idea that was discussed, was specifying a naming convention for any elements that were needed by our Ajax code. We played around on the whiteboard with some ideas and settled on the idea that we’d prefix our id’s with something easy to remember for both designers and developers.

We agreed on… x_ (x underscore), which would make an element id look something like this:


  <div id="x_notification_message">
    ...

x == ajax... get it?

While this adds the strain of typing two more characters to much of our RJS code, we don’t run into Scenario #2 very often anymore.


  render :update do |page|
    page[:x_notification_message] = 'Something exciting happened... and this is your notification!'
    page[:x_notification_message].visual_effect :highlight
  end

or in client-side JavaScript (where we also use this)...


  $('x_notification_message').do_something

I find that this helps our team keep a clear distinction between what can and shouldn’t be changed in the views by our designers. Sometimes they have a good reason to do so, but they know that if there is x_, then they should ask one of the developers on the team for assistance in renaming it without causing any problems in the application. It also allows our designers to add classes to these elements, or style the id that we’ve defined.

Team Response: Wow, was that all we needed to agree on? Hooray!

This leads me to some other problems that have/may come up, but I’ll discuss that in my next post on this topic, when I’ll show you how we can use RSpec to avoid these sorts of designer versus developer problems.

If you’re working in a similar environment, how are your designers and developers working, together, in perfect harmony?

Until next time, remember to hug your designer. ...and if you’re still having developer design your applications, consider hiring a designer. ;-)

UPDATE: changed examples after a few comments about using div_for as another solution. (see comments for details)

Dialogue versus Debate

Robby Russell — Tue, 10 Oct 2006 00:40:00 -0500

How many times have you participated in a conversation with someone and realized that you really didn’t understand what they had said. Or… perhaps you’ve been talking and even though the other person is nodding, you’re not confident that they’ve really heard what you’ve been saying. Yet, you might find yourself nodding in agreement when they speak… and walk away… totally clueless about what you just talked about.

Were you really listening? Were they speaking over your head? Were you speaking over their head? Perhaps you were distracted? Whatever the reason… it’s probably worth thinking about. We all do it from time to time.

Even worse, you were only thinking about how they were wrong and you had the right answer already in your head…

In Dialogue, there are rules for participation, which we’ll explore in future writings.

One might wonder if we’ve been trained to work this way. In school, we had classes that taught us to debate one another… further cultivating a society focused on you versus I. But, what about the community? What about the team? What about us? Sadly, most of the teamwork that we saw encouraged was in the form of sports. To be fair… we did have debate teams… but the purpose was to argue for one side of an argument… not to find a way for both sides to work together. One might wonder our society would be like if we encouraged Dialogue in the same way.

Perhaps we need Dialogue teams. ;-)

Dialogue allows teams of people to work together. It’s a process that cultivates learning and discovery. Dialogue is not a process that encourages the passing of judgement or pushing for specific outcomes… the aim is to share understanding. Through empathetic listening and questioning, the seeds of trust are planted.

Dialogue-Driven Development is about building trust.

I came across this great table, which contrasts Dialogue and Debate. It’s worth taking a few moments to review.

Here are a few that caught my attention…

Dialogue	Debate
Dialogue is collaborative: the sides work together.	Debate is a type of fight: two sides oppose each other to prove each other wrong.
In a dialogue the goals are finding common ideas and new ideas.	In a debate the goals is winning with your own ideas.
In a dialogue you contribute your best ideas to be improved upon.	In a debate you contribute your ideas and defend them against challenges.
In a dialogue you listen to each other to understand and build agreement.	In a debate you listen to each other to find flaws and disagree.
In a dialogue you may consider new ideas and even change your mind completely.	In a debate you do not admit you are considering new ideas and you must not change your mind, or you lose.
Dialogue encourages you to evaluate yourself.	Debate encourages you to criticize others.
Dialogue promotes open-mindedness, including an openness to being wrong.	Debate creates a close-minded attitude, a determination to be right.

There is something to be said about the art of Dialogue, which is why we’re so excited about the d3 project.

Project Enlightenment with d3

Robby Russell — Wed, 27 Sep 2006 02:38:00 -0500

What do we mean exactly when we say that we want to participate in thoughtful dialogue in a project? What is our intention with this? When I recently came across some essays by David Gurteen and read his definition of dialogue as being “a disciplined form of conversation” it got me thinking about how we often forget that like all skills, practice makes perfect. What make our conversations discilplined in the first place? Based on my experience, dialogue (disciplined conversation) manifests when all participants in a conversation are practicing mindfulness. I don’t believe that most people learn or behave well by being beaten into submission, so we must come to an understanding while we actively involve ourselves in dialogue. Most of us are civil towards one another, which does wonders for allowing us to tolerate each other, but I still can’t help but feel that we’re still missing the mark when it comes to having consistent and thoughtful dialogue.

Over the past several months, our team has been spending quite a bit of time and energy analyzing these problems. What we really starting to uncover is that the real problem seems to exist somewhere outside of our development methodologies. Working under the Agile umbrella provides no silver bullet. The real issues seem to exist much deeper in our human nature.

We’re not all that great at communicating

Humans are not perfect… therefore… our ideas are probably far from perfect as well. Our thoughts aren’t perfect. Our interactions aren’t perfect. We’re consistently inconsistent (heh) and while we can rely on averages to some extent to calculate probabilities, we can’t always explain why somethings still go horribly wrong. The principles outlines in the Agile manifesto stress the importance of focusing on people not processes and responding to change. If we are to put a heavy focus on the people involved in projects, we must acknowledge our strengths and weaknesses and find innovative ways to improve our communication skills.

On a daily basis, we’re faced with complex problems. Hopefully, we’re using a lot of our prior experience to aid us in making rational decisions about how we respond to them. There is a lot that goes through each decision that we make. We can’t automate this process (yet), but we can definitely share our lessons with one another. Our intentions need to be thoughtful and empathetic to the needs of all parties affected by each decision. As humans, we have the opportunity to really listen to the concerns of others and use not only our logical intelligence… but also our emotional intelligence.

Much of this comes down to each of us learning to understand how we make decisions and interact with people. It’s our goal with Dialogue-Driven Development that with your help, we’ll be able to outline patterns of dialogue, which we hope will be of great value to the community. Our team has been analyzing our interaction with clients and discussing what has worked well and what hasn’t. How did our clients respond to approach X versus Y? It’s important that we capture this information and have conversations about the results.

“The meaning is what holds it [dialogue] together. ..Meaning is not static – it is flowing. And if we have the meaning being shared, then it is flowing among us; it holds the group together…in that way we can talk together coherently and think together.” – David Bohm

Doesn’t that sound beautiful? Who wouldn’t want to reach such levels of project enlightenment?

d3 aims to be to communication what BDD is to specification

While at RailsConf Europe, I had the privilege to speak with several Rail developers… several of which are doing contract development for several clients, just like our team. We discussed d3 for a while and I walked away feeling really excited about the whole concept. When I explained that our team didn’t see d3 as a replacement for Agile methodologies like Scrum, XP, etc… but as another tool in our tool belt. Dialogue between developers, clients, and users should be agnostic about particular methodologies. We’re really excited about Behavior-Driven Development as a best practice in our development process and we’re seeing Dialogue-Driven Development as another best practice that we start using from the initial point of contact with a potential client to long after we deliver the working product that we were contracted to develop.

We’ll be posting some fun announcements about the d3 project in the coming week(s). Stay tuned…

Borat finds a new stakeholder

Robby Russell — Fri, 09 Jun 2006 08:23:00 -0500

Picking up on my last Borat post, Prototypes Are Your Friends, I would like to direct you over to the next post in the series, G’day Project Borat where Brian Ford jumps into the game…

“When we, as developers, began focusing on user-centric design and usability, it was a recognition that users deserved respect and need not be rescued, if you will, by our bright ideas. In a big way, we needed to keep our bright ideas out of the user’s way.”

Code Complete

Robby Russell — Thu, 08 Jun 2006 11:11:00 -0500

I came across a review of Code Complete, 2nd Ed. last night… and saw the following quotes.

””People have already made all the mistakes that you’re making now, and unless you’re a glutton for punishment, you’ll prefer reading their books and avoiding their mistakes to inventing new versions of old problems.” “

...and

””Once a programmer realizes that programming principles transcend the syntax of any specific language, the doors swing open to knowledge that truly makes a difference in quality and productivity.”“

I’m sold and with 900+ pages… I’m sure I have a few things to learn. I’m going to go pick it up shortly at Powell’s Technical. :-)

Keeping Prototypes is a Bad Idea

Robby Russell — Sat, 11 Mar 2006 08:30:00 -0600

In a recent article titled, Just Build It: HTML Prototyping and Agile Development on Digital Magazine, Garrett Dimon writes,

“You need to temporarily suspend any notions that prototyping is always throwaway work. If you approach it as throwaway work, it will be. However, if you approach it with the intention of keeping it, you can create modular code that can be reused.”

I disagree. :-)

I’m not a HTML web designer, but when building applications, a prototype should be looked at as a process in which you agree that what is built will and should be thrown away.

Why?

When you are in prototyping mode… you should be very aware of the fact that it is a prototype. This is your chance to take shortcuts, break the rules, get creative, and express your ideas on a piece of paper, in plain HTML, or perhaps you may even run ./script/generate scaffold to spit out some code that you know will not be used in a production application later on. The goal here is to figure out what direction you want to take the project and get the client to sign off on these ideas… not to build reusable and modular code. If you’re building a prototype with the goal of reusing it than it’s likely that you’re spending too much time doing it.

Just Toss It

While you might not physically toss your application into a nearby trash can, you should aknowledge and remove any attachments that you may have that suggest that the prototype was a waste of time because no reusable artifacts came out of it. It’s the ideas that are expressed here that make this time valuable. Perhaps you don’t need a prototype phase… this would mean that you know exactly what you are about to develop. If you go the route of prototyping and find it to return nothing useful… than imagine how you’d feel if you just started developing and determined that you really missed an important requirement a few weeks later.

“The physicist’s greatest tool is his wastebasket.”
- Albert Einstein

The shortcuts that you should have taken earlier have likely created too much technical debt in your code. A fresh start should be the next step. Prototyping is part of the development process but the moment you allow yourself to think that you should reuse some of the prototype in your application is when you begin to become too attached to the notion that your prototyping phase was a waste of time end energy. Go into the prototype phase knowing that reusable artifacts are not the goal of this phase. Throw it away. ;-)

“Every act of creation is first of all an act of destruction”
- Pablo Picasso

Keep The Lessons and Ideas

You don’t need to rm -rf the_prototype but you should be very honest with both yourself and your client that the prototype phase is a way to quickly express an idea or process in a both a technical (and often) visual manner.

Prototyping Generates Confidence

Clients have (many) ideas. I hate to be the one to break it to you, but it’s almost certain that they are not as confident in you as you would like to believe. Confidence evolves over time and should be nourished on a regular basis. Their ideas are important to them and they are paying you to be part of the execution of those ideas. If you even remotely sense that you are not confident in their ideas… tell them this. Prototype their ideas. It could save both you and your client a lot of time, money, and resources in the long run… especially if an idea proves to be too complicated to execute.

Ideally, this is when you both agree that this idea is a good idea and that you both understand how it will be executed. This is both a good and healthy process. :-)

Document your learnings, the changes presented by both your client and yourself, and then revisit your Use Cases.

What you are about to build is that much clearer now. This feeling of clarity is exactly why you created a prototype. Remind yourself of this.

Always Start Fresh

Now that the client and you have come to an agreement about what is to be developed… the next phase should begin.

rails the_real_app

...and remember… don’t be afraid to revisit prototyping again. If an idea is not clearly defined yet, whip up a new prototype and see what comes of it. Just keep it out of your code base…. and if it’s already happened… please Refactor. ;-)

Like I said… I am not a HTML person… reusing the colors, graphics, and html artificats that you worked on might be useful… but modular code shouldn’t fall out of a prototype.

However, prototyping is a good idea and I highly encourage it.

Prototyping can also be extremely fun!