Setting up a new website: user stories, installing Source locally, and lessons learned

27 April 2014

Over the past couple of weeks, I've been focusing my efforts at work on the online presence of my project, the Open Development Toolkit. I put up a holding page there at the start of the year, which runs on Jekyll and was forked from another site; I kind of love the site (you'll understand when you click the 'on' button in the top left hand corner), but it doesn't do everything I needed to do.

So, with the help of my lovely tech mentor Tryggvi, I began (and am still in) the process of restructuring things.

Firstly, to work out what I needed from the site, I wrote some user stories, thinking about the people who would be accessing the site, what they wanted to do, why they wanted to do it. I prioritised them in terms of the most important users down to the least important users, and tried to limit myself to just 6 different users, most of which have more than one story. From these, we worked out what feature they would need on the site to be able to do what they wanted to; it turns out that a few of them brought up the same feature, which was really helpful to see.

A couple of examples:

User: Journalist in aid-recipient country

I want to: find a tool to help them understand what projects the World Bank is running in their country

So that I can...investigate the relationship between the World Bank and my government

Feature: tools search function (tag: donor organisation)


User: Civil society activist/newcomer to accessing aid data

I want to: find a tool to help me understand aid flows to their country, + accompanying training materials to work through alongside

So that I can... have some support while beginning to explore the theme of aid data

Feature: tools and accompanying training materials presented together

One of the most important features was being able to clearly see, and filter through, different tools on the site, as well as having a clear online community around the toolkit which allows people to see who is out there, what they're working on, and what they've contributed to. Another was being able to link between tools and training materials in an easy way, to make it as easy as possible for users to find the resources they needed on a thematic basis.

Now, I've been assured that basically all of the features that I needed are entirely possible to create in Jekyll, the framework that I've been using so far; but I have fairly limited time, and I'm such a newbie that I imagine it would take a long time to set all of these things up! (though, I imagine, be a lot of fun.)

So, I started looking for sites which already do lots of the things I want my site to do, and one which came up pretty quickly is Source, from OpenNews. It's a community site, aiming to

amplify the impact of journalism code and the community of developers, designers, journalists, and editors who make it. 

It acts as a hub around journalism code, and seemed from first glances to do everything that I wanted the new Toolkit site to do.

To check, though, I went through my list of user stories and marked how the Source site would fulfil those requirements. I marked the ones that could be easily ticked off with the site 'as is' in green, those which would require some modification in yellow, and those which couldn't be met in red. Luckily, there were no red rows among my user stories! And the yellow ones were reasonably simple modifications.

So, having checked that, the next step was to install a local version of the site, for me to have a play with. I was really lucky to be introduced to the team behind Source at this stage, who were super kind and offered their help in anything I needed to get the site set up. It's been great having that as a back up when I've had questions, and the whole team have been really responsive and generous with their time; a brilliant example of the joys of the 'open' community. 

But to start with, I looked at Source on Github. Luckily for me, there's a pretty comprehensive 'Readme' section with installation instructions. Given my newbie status though, there were still a few things that I needed to install myself, or look up to understand fully. I'd also never used Python or Django before, so came across some pretty basic stuff for the first time. 

I started with the instructions as they read on the readme; I'd never used the command


before, so first I had to install that, and I followed the instructions here. I already had the other dependencies from having Homebrew installed previously.

I ran

pip-install funfactory

(what a lovely name!)

and then I used these instructions on forking the repo from Github's help section.

Then, I learned about what a virtual environment was here, and how to set it up for the first time, by running

pip install virtualenvwrapper

and activated it:

source venv/bin/activate

and changed directory into /code/source, which is where I'd saved the forked directory, before following the last step:

git submodule update --init --recursive

and getting all of the development requirements,

pip install -r requirements/dev.txt

Then, I carried on with the 'Configuration' instructions. I created my own 'HMAC_KEY' and SECRET_KEY in the file /source/source/settings/ (and was assured they could be as silly as I liked)

and I added:

'default': {
'ENGINE': 'django.db.backends.sqlite3',
'NAME': 'source_app.db',

to the same file.

I kept running into errors though, and then realised that I didn't have MySQL, which I had assumed would be there from Homebrew. So, I followed this good advice and ran:

$ brew install mysql

And then, once I had definitely got all the dependencies, I synced:

python syncdb

and migrated articles, code and people as in the Readme.

I couldn't get the test-articles set up, but I ran 

python runserver

anyway, and, to my delight, saw my own local version of it running at  http://localhost:8000/

It was so satisfying! I've no idea how recently other people had tried going through those steps, but I filed an issue about the test articles to let them know, and got a very prompt response, saying the test articles need to be updated. 

Ta-da. And that was that. Next has been learning how to customise it, and diving more into Python and Django... coming in another blog post.

You might also like: