Blog

January 22, 2014 17:46 +0000  |  Employment Software Web Development 0

Every once in a while I hear people speaking with authority about what exactly agile software development is, and the funny thing is, they usually conflict with other statements with similar authority about agile. Often, this is coupled with negative comments about how agile is impractical because X, which is frustrating, because some of my most productive years were spent in a fully agile office environment.

So I thought that I'd write something about agile as well, if for no other reason than to hopefully point people in the direction of what I know to be a very efficient and practical means of getting stuff done. I don't want to claim that this is the One True Way of agile development though, as I'm not interested in having the kind of conversation where we re-classify everything for the sake of giving it a name. My team lead at the time, Mike Gauthier called this system agile, and that's good enough for me.

Talk Less, Code More

The goal behind agile is to have developers spend time doing what they love: rolling code, and to keep them out of meetings they want no part of to begin with. Instead developers have only 3 responsibilities over and above writing code throughout the sprint. I'll cover these in more detail below:

  • A Morning stand up meeting: Every day, 10min
  • Sprint meeting: 1hr
    • 30min to recap the last sprint
    • 30min to prepare the next one
  • Any additional initiative taken to talk to the client about what they want

Note what isn't in that list:

  • Requirements meetings
  • Proposals
  • Logging hours
  • Documentation

The idea behind agile is essentially: "Here's a task, go!". The key to making this work is to keep the tasks simple and concise, so that the result of the sprint is incremental. Read: easy to deploy, with no surprises.

The rapid pace of an agile project means that the usual slow processes of planning meetings and wiki documentation becomes an exercise in futility: the job is done before it's planned, and it's changed not long after it's documented.

Stand Up

It sounds like a pointless process, but it's probably the most powerful part of an agile system. The morning "stand up" meeting, or "scrum" is exactly what it sounds like: the entire team stands up in a corner of the room to answer 3 questions each:

  1. What'd you do yesterday?
  2. What're you expecting to do today?
  3. What happened yesterday that prevented you from doing what you needed to do?

Each developer should talk for no more than a few minutes, answering these questions point blank. It's the opportunity for the team lead to address whatever problems were mentioned (after the meeting), and for other developers to find out that their colleagues are waiting for them to finish something.

Note that this meeting is not for design discussions, or gripes etc. Rather, the purpose is to be a quick update on what's going on -- which is why you're supposed to stand up through the whole thing. The minute someone starts to look like they need to sit, that's your cue that the meeting has gone on too long.

Sprints

Think of sprints as a deploy schedule, but short and seemingly insignificant in what they produce. While a typical software deploy schedule may last months or even years, consisting of massive upgrade paths and a long complex list of changes, sprints are typically 1-2 weeks long. You write the code, and it's live in a few days.

The big difference from other methods is that sprints are incremental, so while new features roll out bit by bit, bugs are fixed weekly with no having to maintain multiple branches for extended intervals.

Keeping the sprint short ensures 4 things:

  • The tasks are always short-term and easy to comprehend both for developers and clients
  • Clients see progress on a regular, predictable schedule
  • Releases are predictable, and easy to break new features into
  • Your team has a concrete and easy to understand goal to work toward

Code Debt

But what about those elaborate project charts with tasks designated to different developers, all colour coded by week, accounting for availability?

Gone. All of it. Throw it out. You now have a binder full of post-its, or if you're feeling all 21st century about it, a Jira task list. This bundle of tasks is your code debt and should not be organised as priorities are expected to change from sprint to sprint. At most the PM should keep a loose tally of priorities, so as to make the sprint planning meetings go smoother.

Chipping Away at that Debt

At the start of every sprint, you hold a meeting in which the project manager talks to the developers about what's most pressing in terms of bug fixes and new features. Importantly, this is a two-way conversation: the PM representing the needs of the client, and the developers representing their own limitations and the quality/maintainability of the code.

This sprint planning meeting is where you take stuff out of your code debt, break it into bite-sized chunks, and assign it to the current sprint. You need to keep the tasks small and easy to achieve in < 4hours. If it takes longer than that, it needs to be broken down. This has a couple big benefits:

  • Big jobs can be spread around, potentially finishing them faster
  • Knowledge sharing is easier as everyone has the opportunity to work on smaller portions of a greater whole.
  • It's an easy way to make big jobs suddenly feel possible.
  • Finishing a task results in a sense of accomplishment for the developers
  • Incremental change gives the client a sense that something is being done

No Ticket, No Work

Now that your sprint planning meeting has broken up a portion of your code debt into tasks, the team is presented with a white board with a simple grid layout:

+--------+--------------+-----------+------------+---------------+
|  Todo  |  Developers  |  Working  |  Finished  |  QA Complete  |
+--------+--------------+-----------+------------+---------------+
|        |  Daniel      |           |            |               |
|        +--------------+-----------+------------+---------------+
|        |  Aileen      |           |            |               |
|        +--------------+-----------+------------+---------------+
|        |  Charlie     |           |            |               |
|        +--------------+-----------+------------+---------------+
|        |  Aisha       |           |            |               |
+--------+--------------+-----------+------------+---------------+

That Todo column is where you put the amorphus blob of post-it notes, each one representing one of the aforementioned bite-sized tasks for this sprint. Note that while in this column, they aren't actually assigned to anyone; they're simply waiting for someone to take them and stick it onto their Working column.

Now, say that there are 30 tasks to complete before the end of the sprint. Aileen sits down at her desk and as she has nothing to do yet, she looks at the board and grabs the post-it about fixing a bug in email notifications. She moves the post-it from the Todo column into the Working column on her row, and opens her editor.

When the job's done, she moves it to Finished, at which point the QA team can now take a look, and when they're happy with the job, they move it to QA Complete. If however her change broke something, or if it's simply unsatisfactory, they move the post-it all the way back to the Todo column, where Charlie might grab it later that day, since Aileen has moved onto another ticket about the statistics engine.

In practise, developers will often gravitate toward tasks they're familiar with, and they'll often leave tickets that have been bounced-back by QA for the initial developer and this can be ok. However if ever one developer becomes a dominant force on a particular component, (s)he might be forbidden from working on it for a while, to make sure that the other developers have a chance to spend some time learning how that software works.

The most important part of this is that developers aren't supposed to do any work unless there's a ticket for them. This keeps people on-task toward completing the sprint on-time and as expected. If there's other work that deserves attention, this is best brought up at the next sprint planning meeting.

Spikes

It's about at this point where people start with comments like "What if the server goes down? Are we expected to wait until the next sprint to fix it?". Obviously not. Emergencies or "directives from on high" are things that can't wait and by their nature they can't be part of the sprint plan. They're also rare, so breaking a working system to accommodate them is a little absurd.

The solution is what's called a "spike". A task injected into the Todo list, typically flagged to be done as soon as possible. Its presence in a sprint taints the sprint, so that it can be pointed to in the event of an overrun:

The server went down on Friday and Aisha had to burn half her day fixing it. As a result, we only finished 33 of our 36 tickets this sprint.

This is the sort of thing talked about in the post-sprint meeting, and if more action is needed (either to fully correct the problem or to avoid future cases) these tasks are added to the next sprint.

So, How'd it Go?

There's one other meeting of consequence. At the end of every sprint, you meet to talk about how the sprint fared: what went well, what didn't. In those 30 minutes, you talk about how awesome the QA team was, and how much it sucked when that module we thought would save us work turned out to create more than it solved. It's important to use this time to blow off steam and celebrate the accomplishments of the previous sprint and to take some time to figure out what could have gone better. It facilitates knowledge sharing more than anything else, and allows the PM and team lead to make better decisions in the future.

Documentation

The one thing people freak out about most when I talk about this method is the lack of documentation. They conjure up nightmare scenarios where one of the developers is hit by a bus and "no one knows how their stuff works", or point out that new developers won't have anywhere to start. Both of these are non-issues though, so long as you stick to the process and don't write terrible code.

If any member of the team doesn't know how a component works enough to get in there and complete a task, then it's time to get that person working on one of those tasks. Knowledge transfer happens best through doing, which means making sure that every member of the team has her fingerprints on every part. To put it in real terms, if Daniel gets hit by a bus, the project can go on because Aileen, Charlie, and Aisha have all spent some time poking at the payment engine. Not one of them wrote the whole thing, but the understanding is there.

Of course this can only happen if the code is readable and adheres to established standards. Variable names should be in the common language of the team and be whole words, method calls should be given names that explain what they do, and class names should make sense as singular objects. If the code can't be understood by someone who's never seen it before, then it's broken by design. Making sure that everyone has an opportunity to interact with this code is the best way to ensure it's readability.

Be Rigid

Probably the hardest part of agile software development is sticking to the process. As simple as it is, it's just too easy to fix a bug that someone found that isn't in the sprint, or add a simple feature that the client mentioned earlier that day. If agile is going to work, this can't be allowed to happen, and a lot of people have a hard time with this.

What you have to remember is that while the process feels pointlessly rigid, it's there to protect the team and ensure that the client gets exactly what was promised on the schedule that was promised. Adding in bug fixes can potentially derail the schedule, or introduce bugs that shouldn't have been there in the first place. It teaches the client that she can have whatever she wants whenever she wants, and as it's not part of the agreed sprint, she may try to get away with not paying for it.

From the developer side, it's important to remember that we like lists. If we can look at the list of stuff to do and know that that's all that's ever going to be there for the whole sprint, this introduces a sense of calm, and knowing exactly what's expected.

To this end, it's important to reward a team that manages to complete its sprint ahead of schedule. If they get everything finished by Thursday, let them take Friday off. The project is exactly as far along as you expected, so why not? Similarly, if the team is routinely late in completing the sprint, overtime is justified since the entire team helped write the sprint schedule during the planning meeting.

Conclusions

What makes agile work is having a simple and concise plan to follow, that has been agreed upon by all parties. I've worked at companies that implement this system without involving the developers so the schedule is imposed by people who have no knowledge of what actually needs to be done. I've also worked at companies where the developers run the schedule, which is to say, there's barely any schedule at all and the results are products that "mostly work", according to whatever the developer at the time thought was appropriate. As with so many other things, the key is openness, honesty, and inclusion in the process for all sides.

Agile is a system that everyone understands and agrees to, but doesn't get in the way of actually getting stuff done. It protects all parties involved from undue stress, and unexpected results, and I can honestly say that it was (at least for me) the best system to work with.

January 03, 2010 12:07 +0000  |  Django Facebook Python Software TheChange.com Web Development 2

This is going to be a rather technical post, coupled with a smattering of rants about Facebook so those of you uninterested in such things might just wanna skip this one.

As part of my work on my new company, I'm building a syncroniser for status updates between Twitter, Facebook, and our site. Eventually, it'll probably include additional services like Flickr, but for now, I'm just focusing on these two external systems.

A Special Case

Reading this far, you might think that this isn't really all that difficult for either Twitter or Facebook. After all, both have rather well-documented and heavily used APIs for pushing and pulling data to and from a user's stream, so why bother writing about it? Well for those with my special requirements, I found that Facebook has constructed a tiny, private hell, one in which I was trapped for four days over the Christmas break. In an effort to save others from this pain, I'm posting my experiences here. If you have questions regarding this setup, or feel that I've missed something, feel free to comment here and I'll see what I can do for you.

So, lets start with my special requirements. The first stumbler was the fact that my project is using Python, something not officially supported by Facebook. Instead, they've left the job to the community which has produced two separate libraries with different interfaces and feature sets.

Second, I wasn't trying to syncronise the user streams. Instead, I needed push/pull rights for the stream on a Facebook Page, like those created for companies, politicians, famous people, or products. Facebook claims full support for this, but in reality it's quite obvious that these features have been crowbared into the overall design, leaving gaping holes in the integration path.

What Not to Do

  • Don't expect Facebook to do the right/smart thing. Everything in Facebookland can be done in one of 3 or 4 ways and none of them do exactly what you want. You must accept this.
  • Don't try to hack Facebook into submission. It doesn't work. Facebook isn't doing that thing that makes sense because they forgot or didn't care to do it in the first place. Accept it and deal. If you try to compose elaborate tricks to force Facebook's hand, you'll only burn 8 hours, forget to eat or sleep in the process and it still won't work.

What to Do

Step 1: Your basic Facebook App

If you don't know how to create and setup a basic canvas page in Django, this post is not for you. Go read up on that and come back when you're ready.

You need a simple app so for starters get yourself a standard "Hello World" canvas page that requires a login. You can probably do this in minifb, but PyFacebook makes this easy since it comes with handy Django method decorators:

# views.py
from django.http import HttpResponse, HttpResponseRedirect
import facebook

@facebook.djangofb.require_login()
def fbCanvas(request):
    return HttpResponse("Hello World")
Step 2: Ask the User to Grant Permissions

This will force the user to add your application before proceeding, which is all fine and good but that doesn't give you access to much of anything you want, so we'll change the view to use a template that asks the user to click on a link to continue:

# views.py
from django.shortcuts import render_to_response
from django.template import RequestContext
import facebook

@facebook.djangofb.require_login()
def fbCanvas(request):
    return render_to_response(
        "social/canvas.fbml",
        {},
        context_instance=RequestContext(request)
    )

Note what I mentioned above, that we're asking the user to click on a link rather than issuing a redirect. I fought with Facebook for a good few hours to get this to happen all without user-input and it worked... sometimes. My advice is to just go with the user-clickable link. That way seems fool-proof (so far).

Here's our template:

<!-- canvas.fbml -->
<fb:header>
    <p>To enable the syncronisation, you'll need to grant us permission to read/write to your Facebook stream.  To do that, just <a href="http://www.facebook.com/connect/prompt_permissions.php?api_key=de33669a10a4219daecf0436ce829a2e&v=1.0&next=http://apps.facebook.com/myappname/granted/%3fxxRESULTTOKENxx&display=popup&ext_perm=read_stream,publish_stream,offline_access&enable_profile_selector=1">click here</a>.
</fb:header>

See that big URL? It's option #5 (of 6) for granting extended permissions to a Facebook App for a user. It's the easiest to use and hasn't broken for me yet (Numbers 1, 2, 3 and 4 all regularly complained about silly things like not having the app instaled when this was not the case, but your milage may vary). Basically, the user will be directed to a page asking her to grant read_stream, publish_stream, and offline_access to your app on whichever pages or users she selects from the list of pages she administers. Details for modifying this URL can be found in the Facebook Developer Wiki.

Step 3: Understanding Facebook's Hackery

So you see how in the previous section, adding enable_profile_selector=1 to the URL will tell Facebook to ask the user to specify which pages to which she'd like to grant these shiny new permissions? Well that's nifty and all, but they don't tell you which pages the user selected.

When the permission questions are finished, Facebook does a POST to the URL specified in next=. The post will include a bunch of cool stuff, including the all important infinite session key and the user id doing all of this, but it doesn't tell you anything about the choices made. You don't even know what page ids were in the list, let alone which ones were selected to have what permissions. Nice job there Facebook.

Step 4: The Workaround

My workaround for this isn't pretty, and worse, depends on a reasonably intelligent end-user (not always a healthy assumption), but after four days cursing Facebook for their API crowbarring, I could come up with nothing better. Basically, when the user returns to us from the permissioning steps, we capture that infinite session id, do a lookup for a complete list of pages our user maintains and then bounce them out of Facebook back to our site to complete the process by asking them to tell us what they just told Facebook. I'll start with the page defined in next=:

# views.py
@facebook.djangofb.require_login()
def fbGranted(request):

    from cPickle import dumps as pickle
    from urllib  import quote as encode

    from myproject.myapp.models import FbGetPageLookup

    return render_to_response(
        "social/granted.fbml",
        {
            "redirect": "http://mysite.com/social/facebook/link/?session=%s&pages=%s" % (
                request.POST.get("fb_sig_session_key"),
                encode(pickle(FbGetPageLookup(request.facebook, request.POST["fb_sig_user"])))
            )
        },
        context_instance=RequestContext(request)
    )
# models.py
def FbGetPageLookup(fb, uid):
    return fb.fql.query("""
        SELECT
            page_id,
            name
        FROM
            page
        WHERE
            page_id IN (
                SELECT
                    page_id
                FROM
                    page_admin
                WHERE
                    uid = %s
            )
    """ % uid)

The above code will fetch a list of page ids from Facebok using FQL, and coupling it with the shiny new infinite session key, bounce the user out of Facebook and back to your site where you'll use that info to re-ask the user about which page(s) you want them to link to Facebook.

Step 5: Capture That page_id

How you capture and store the page id is up to you. For me, I had to create a list of organisations we're storing locally and let the user compare that list of organisations to the list of Facebook Pages and make the links appropriately. Your process will probably be different. Regardless of how you do it, just make sure that for every page you wish to syncronise with Facebook, you have a session_key and page_id.

Step 6: Push & Pull

Because connectivity with Facebook (and Twitter) is notonoriously flakey, I don't recommend doing your syncronisation in real-time unless your use-case demands it. Instead, run the code via cron, or better yet as a daemon operating on a queue depending on the amount of data you're playing with. However you do it, the calls are the same:

import facebook

# Setup your connection
fb = facebook.Facebook(settings.FACEBOOK_API_KEY, settings.FACEBOOK_SECRET_KEY)
infinitesessionkey = "your infinite session key from facebook"
pageid             = "the page id the user picked"

# To push to Facebook:
fb(
    method="stream_publish",
    args={
        "session_key": infinitesessionkey,
        "message":     message,
        "target_id":   "NULL",
        "uid":         pageid
    }
)

# To pull from Facebook:
fb(
    method="stream_get",
    args={
        "session_key": infinitesessionkey,
        "source_ids": pageid
    }
)["posts"]

Conclusion

And that's it. It looks pretty complicated, and... well it is. For the most part, Facebook's documentation is pretty thorough, it's just that certain features like this page_id thing appear to have fallen off their radar. I'm sure that they'll change it in a few months though, which will make my brain hurt again :-(

March 11, 2009 01:08 +0000  |  Geek Stuff Korea Web Development 0

I know that I'm in Korea and I "should" be out seeing the sites, but I have to explain that the primary reason for my visit here was less to see Seoul and more to see Shawna and just... relax. Since Shawna works during the day, I took the morning and after noon off to just do nothing yesterday and today I'm catching up on my crazy-sized email backlog. I'll be going out around 11am though with a friend of Shawna's to do some exploring and pick up a temporary phone.

For the moment though, I just wrote a rather long email to my uncle to help him with his Google ranking and figured that since this was the second time I've had to go through all of this with someone, that it might be a good idea to post it all here for future reference. If you think that I've missed anything, please let me know and I'll update.

Google bases your page rank on a few things: linkage, content, and formatting. I believe that it's even in that order. I'll explain one at a time.

Linkage

The number of links to your site and the ranking of the origin sites. So for example if "Bob's blog" links to you, that link is worth significantly less than if it were from Amazon.com or Slate etc. More links is better, and Google will even attribute the content of the origin site to your own. In other words, if a site about Pizza links to you, Google will assume that you have something to do with Pizza. So the best links to get are things *within your field* rather than from anywhere lest you run the risk of diluting your rank with non-relevant rankings.

Content

This is the easiest, but a lot of people miss it. First of all, so-called "rich media" isn't recognised by Google (and pretty much all other search engines too). Flash, Youtube, Silverlight etc. won't get read by Google so don't make your site dependent on such formats. Instead, lots of relevant content with links to other sites and proper use of keywords with which you want to be found.

For example, on my dad's site, he wanted to be found with the keyword "optical" but we never once used it on his site. Instead, we used "optician". As a result, he was #1 for "optician Kelowna" but had no mention for "optical".

It's also important to note that grammar is important. You can't just fill up the page with abnormal uses of keywords you for which want to be indexed. Google pays very smart people a lot of money to write code that will recognise poor-grammar-as-planted-keywords so don't mess with a good thing. The truth of it is that if you have a good site with relevant content, people will find you, link to you and your rank will improve over time.

Format

Back when I was in school we were taught that the format of your code was relevant to your search ranking. I'm not sure of how true this is anymore but it's a good practise nonetheless. Do put headers in header tags (<h1>..<h6>), put text in the alt="" portion of your <img> tags and don't try to screw with them by putting a bunch of keywords in a text block and then hide it by making the text the same colour as the background or by hiding the box altogether. They hate that and their scripts catch you, you risk being delisted.

Lastly, a handy thing to do is to install Google Analytics. It will do fun stuff like track page hits by hour, week, and month as well as give you country of origin stats, search engine references etc. It's awesome and it's free (as in beer, not Freedom).