Back in 2006 I had just started really getting into the sport of footbag.
Being that I didn't have an innate natural talent for the sport it took me
quite a long time to learn the basic techniques. One thing that I frequently found
myself doing was trying to look online for good technique advice whenever I was trying
to learn something new.
There were a few online forums where you could go and ask people about advice for tricks.
The sport is uncommon in the way in which some of the best players were highly
accessible and would answer questions that newer players had.
Despite this many players had trouble finding good information about techniques.
The problem wasn't the quality of the information, it was finding the info.
Some of the best info was buried in forum posts and was really hard to find.
And you couldn't easily find anything at all if you didn't already know the nicknames of moves.
So I realized that a website with a catalogue of moves along with associated trick tips
would be a good resource. Just making it easier to find the relevant information would have
been a huge help to me when I was starting out and would no doubt be a huge help to new players now.
I made a website that contained a catalogue of the moves in freestyle footbag
along with some tips/advice around 2006-2007.
However the site never really got to be as useful as I would have hoped.
Sure there there were some technical issues but even if I had the technical proficiency I
had now I doubt it would have been a huge success.
There were conceptual issues with the approach I took that would have got in the way of a
really useful end product even if the implementation of that approach was perfect.
Now that I've had a few years to learn things and think about a better approach to making
this work I've decided to try to get this project going again.
Given that I'm trying to learn more about Python web frameworks it seemed like
trying to do this footbag project again using Django would be a win.
I bought some domain names and I decided to put the code up on GitHub
In order to actually get it right this time around it's really important to look back
and reflect on what happened the first time I tried this. By learning from the mistakes
of the past there's a chance of not repeating them.
The conceptual issues that the old site had mostly fell into 2 categories:
Content creation issues:
The big issue with the first site was the UI/UX was not particularly good.
Adding content to the site and performing administrative tasks wasn't anywhere
near easy enough. With any collaborative project like this a crucial goal has
to be making it as easy as possibly for your collaborators to collaborate and add
content. The site really fell short in this regard.
The interface to add new information was pitiful. There was no way to keep track of revisions
and undo changes. If you changed something then that change was final. If you accidentally
deleted a page it was gone and you had absolutely no recourse. Some of the reasons for this
were of a technical nature that I address in the technical issues section below.
Regardless of the technical reasons the result was a bad UX as it made it way too easy
for content to get damaged either accidentally or deliberately.
The other thing was that severely lacking were administrative/moderation helpers
which made maintenance much harder that it needed to be.
For example if a link was dead or other parts of a page were in some bad state
there was no internal mechanism to flag it. The only thing you could do was write
an email or get in contact with someone via some other means to alert them to the issue.
A few things really got in the way of the site being "user friendly".
Given that the site was designed with the express purpose of trying to make it
as easy as possible to find relevant information about techniques you want that
part of the site to be as easy to use as possible.
A recurring issue was the difficulty in effectively searching the database.
Unfortunately you could only search based on one string of text and some modifiers
in some checkboxes. The interface was very clumsy and wouldn't return any results
if your search query didn't exactly match a name already in the database.
So if your local community spelled something in a slightly different way then your
search just wouldn't find anything at all.
Unfortunately this meant that you still needed to know the names of things you were
searching for in order to get access to the information.
The irony of this was not lost on me at the time but I hadn't come up with a better solution yet.
You could mitigate the issue of people not knowing the right keywords by creating
additional tutorial materials to help people get started.
Next time I attempt something like this I will be sure to expend a lot more effort
describing the component movements from which everything else is built.
When people know the basics it's much easier to bootstrap this knowledge.
However this doesn't solve the problems created by requiring people to know the names
ahead of time. After all footbag is just a sequence of movements you make with your
body and fundamentally the only requirement you really need is to be able to
describe those movements. Being able to search for information based on the movements
and not necessarily the names of the movements will make the whole project a lot
I feel as though this should be reflected in the UI/UX decisions.
So something that will feature much more clearly in the UI/UX will be emphasizing
that any move is made up of constituent components. When viewing any move
you can easily look up the information about the components via a link.
The other thing that's important is going to a lot of effort to describe the
base movements as these are the building blocks for everything else.
In order to make this huge pile of information easy to use really requires
One of the big realizations I had was that there is a pile of related metadata
and I just wasn't using it effectively in the old site.
In any sort of project like this using the metadata effectively is very powerful.
Given that we are dealing with information here it should be no surprise that
metadata is important. For example it gives you the ability to do fuzzy searches,
create suggestions for other moves and helps you locate relevant information.
Essentially I was just using the move nickname with Job's notation and storing
each component in a SQL database. There was a lot of other information but it either
wasn't stored in the database or wasn't easily accessible.
There's a lot of possibilities if you can let people have logins to the site.
This goes far beyond content entry and maintenance of the information contained in the site.
There's a lot of scope for personalized information about footbag.
People can save tricks they are working on and keep track of their progress in
the sport. You can offer personalized suggestions to people for technique pages
that might be relevant to them. There's a bunch of other uses of this information
that could potentially help people learn better.
While I had hacked around with some code in 2006 I didn't have a good understanding of software engineering and
the code had all the hallmarks of someone who was an inexperienced programmer.
In all honesty it was the classic PHP noob site, basically it was a total mess.
As a software professional I would be extremely embarrassed to have such a low quality
piece of software attributed to me these days.
Since 2006 I have learned a bunch of very important things about software engineering
and web development. I'm proactively thinking about maintenance now and the full life
cycle of the website.
Code readability is vastly better, everything is documented and I'm using the PEP8 style guide for the Python code.
Due to better software engineering practices the chances of anything catastrophic
derailing the project is much much lower.
Here's a short list of specific problems and shortcomings from last time that I aim to solve this time:
- I wasn't using version control software and had an ad hoc way of keeping the source in tarballs.
This time I'm using Git for everything and I'm regularly keeping backups of the databases.
These database backups are automated too.
- No thought was put into the deployment of the site. It was just running on a cheap web
hosting provider and I FTPed files directly to the live site hosting directory when I needed.
- I'm using pythons virtual environments to try to keep a stable snapshot of
the packages that the environment requires.
- Development and the live site are in different locations and I'm using
a one step deployment with Git/Fabric now (no more oops I made a small mistake and brought down the live site again)
- I didn't automatically test the code. I didn't even know what a unit test was back then let
alone how to effectively use them. Integration testing involved loading the page in the browser and randomly clicking links for a few minutes.
This time I'm thinking that I might even set it up so that it automatically aborts the deployment if the certain tests fail.
- Last time a lot of operations that involved updating the database could only be done
via writing direct SQL queries. A lot of people who are interested in contributing to this
project won't know the first thing about SQL and really they shouldn't have to.
This time I'm using Django and making a user interface for adding content that requires no programming skills.
The entire focus this time around is on making it as easy as possible for the community to participate,
if people have to be programmers to participate that's way too much of a barrier to entry.
- Last time I handled the SQL part really badly:
- The trick tips was stored in the DB as this huge varchar that just contained HTML.
Because this needed to fit the largest page this was tremendously inefficient with
regards to space. Next time I think the idea will be to use something more like a wiki
approach for the tips/advice section and have the database just point to that page.
- The interface to update the database was completely open to SQL injection attacks.
I didn't use prepared statements and I definitely didn't sanitize the input well enough.
Ultimately no beginner ever sanitizes the input well enough and I being a beginner was no different.
The search might have been vulnerable to attack too, chances are I didn't sanitize that
input well enough because even though parts of the search used prepared statements
there may have been string concatenation somewhere in those pages.
- I didn't use transactions for the SQL queries and the PHP side just didn't handle SQL
errors properly. Whenever something went wrong it would mostly just die or enter into inconsistent states.
- Videos had to be uploaded in whole somewhere and you had to link to them with an external link.
This time around I will give users the option to add videos via video API's such as youtube.
There's a few reasons I think this is a big win:
- This allows you to timestamp videos and just pull out the relevant part from other videos.
When you are trying to make a catalogue from scratch that contains video demonstrations of
a large number of techniques it helps a lot to be able to look through
existing video footage, even if it wasn't made specifically for this purpose, and pull out any
clips that are appropriate. Many of these video API's allow you to link to a beginning and
ending timestamp and only that portion of the video is actually downloaded. This saves a
lot on bandwidth usage.
- Videos were not displayed on the same page as the other information about a techniques,
you had to follow a link. While it's not a total deal breaker I think the UI/UX is better
if you can have all the information at once. So this time I will use a video API to display
the videos on the same page if that's possible.
- Support for readable URLs was poor to say the least. I did think about it and I implemented
something but it just didn't work particularly well. This time I'm really wanting better URLs
so you can just go to /move/clipper and have confidence that it will work instead of
needing to send people links like /move/move.php?id=1f17g9f01g1f.
- The security of the data was, by professional standards, very poor. I at least knew that
you shouldn't store passwords in plaintext but I just had a bad encryption algorithm.
Now I know more about that and logins will be hashed+salted and not encrypted.
This way the even if the database gets compromised people's passwords hopefully won't get exposed.
- I'm just a lot better at programming. I've learned some really hard lessons in the last few years
about how to do things properly. I'm hoping that the quality of code I write this time around will
be much higher. If the project ends up getting some collaborators I'm hoping that I can provide
some mentoring to people and pass on some of my knowledge in this area.
- I wasn't using an issues tracker. For example all of the issues I have listed here would have gone
into the issues tracker if that website still existed. This time I'm using the GitHub issues tracker