Training session August 2011: Coding and Challenges, by Jenny S-T (AD&T)
This training session was led by Jenny S-T, Training lead for Accessibility, Design, & Technology (AD&T), and covered coding and the challenges feature of the Organization for Transformative Works' Archive of Our Own software. If you are interested in volunteering as a coder for the OTW, please contact the Volunteers & Recruiting committee--we'd be happy to have you!
Accessibility, Design, & Technology is the guiding body that coordinates software design and development on behalf of the Organization for Transformative Works.
This transcript has been edited for clarity.
Jenny S-T I'll do some general intro, but it's good to know what people know already. I'm planning to take the first 20 minutes or so to talk about coding, then talk about challenges, then have a good chunk of time at the end for more questions and discussion.
Trainee 1 I know nothing. That sounds good to me.
Trainee 2 I'm with Trainee 1 on both counts :)
Trainee 3 same
Trainee 4 me too
Trainee 5 I know some; I'm looking for what are good projects to start with if I am ready to start coding.
Jenny S-T So, on the AO3, we use two main tools, Github and Google Code. For experienced coders, you can jump straight in and make pull requests on Github. Bugs and planned features are listed on Google Code. If you've never coded before, that's totally fine! We'll help you through it all. The Archive is deliberately coded in a language that is easy to learn - we tested several to compare!
Jenny S-T For those who aren't familiar with it, the Archive is coded in Ruby on Rails, and we use Git for version control, so those are the things to look up. Git is very powerful, but the basic commands are pretty simple, and our tutorials on the wiki go through the ones you need most often.
We also offer what we call "webdevs", which are hosted environments with everything set up for you already. We strongly recommend these for anyone who's not already an expert. It makes life much easier, and you can dive in to the interesting bits.
To start with, we recommend two main tutorials: TryRuby (http://tryruby.org/) and Rails for Zombies (http://railsforzombies.org/). You can work through those by yourself, or pop into our chat room for help and encouragement. The coders chat room is open to all at this guest URL: https://fanarchive.campfirenow.com/7e097
So for Trainee 5, you can browse through the list in Google Code for anything with "Priority=High", or ask AD&T or in the Coders chat room, and someone will suggest something.
There are also issues helpfully labelled "Difficulty=Easy" in Google Code, which are good ones to start with, for getting familiar with the code.
Jenny S-T If you're starting from scratch, have a look at those two tutorial websites - they're both interactive, and once you've completed those, we've then got Archive-specific tutorials. And if the learning style doesn't suit you - e.g. if you prefer books to videos, we have some recommendations in the wiki: http://wiki.transformativeworks.org/mediawiki/Getting_to_Grips_With_Ruby... (link is accessible to current volunteers, and contents are repeated below)
Jenny S-T Book recommendations from the wiki: We have an OTW coders copy of the Agile Rails book, which is a great reference and also takes you through creating a sample project. Ask in the coders chatroom for a copy.
Getting Started With Rails is a great tutorial for Rails 2.3 - one of the few really up-to-date ones out there. It takes you through the same set-up and blog project as out tutorial, but with a lot more explanation about the structure of Rails and the principles behind what you're doing. Highly recommended.
Free excerpt of Simply Rails 2 PDF download of the first 4 chapters of the book "Simply Rails 2" contains some excellent explanations of concepts (objects, methods, MVC, etc.) for real beginners and an overview of Ruby and Rails.
Ruby On Rails Essential Training is a set of video tutorials. It's now very out-of-date, but the explanations of how Rails actually works are very clear and still essentially valid. You have to pay to access the full suite, but the ones available for free are worth a look at.
Railscasts are a series of screencasts on many different aspects of Rails. They include tutorials on different methods in Rails, implementing specific plugins, and lots more. Well worth a look at.
Trainee 7 I guess the part I'm confused about more than how the code works is how you get to actually....do code on the site. Do you volunteer officially or register or?
Jenny S-T If you're keen, volunteer officially at http://transformativeworks.org/contact/volunteers%20and%20recruiting. Experienced coders can submit pull requests direct to github, but if you fill in the form, we'll add you to the mailing lists and invite you to training and stuff. If you're interested but not sure yet, have a look at TryRuby and Rails for Zombies first, then fill in the form if you like it.
Jenny S-T So, let's move on to challenges for a little bit. Do we have anyone who's specifically here for help moderating a challenge, or more for the general knowledge?
Jenny S-T Challenges are a big and fairly complex feature on the AO3. Anyone who's tried to set up and moderate a challenge will have faced this, or even just the intimidating sign-up forms for Yuletide last year. We've got plans to improve things and make it all more usable, but we don't want to remove options that people use, so it's never going to be that simple. Even if you're not planning to moderate a challenge any time soon, it's useful to have more people who understand enough to be able to test it.
We have some handy tutorials: Participating in a prompt meme (http://archiveofourown.org/admin_posts/147), setting up a prompt meme (http://archiveofourown.org/admin_posts/146), running a gift exchange (http://archiveofourown.org/admin_posts/75).
So, first, the structure. A collection can have sub-collections. (Only one level of nesting, though!) A collection or a sub-collection can be a challenge. For a one-off, you'd have a collection that's a challenge. For a multi-year thing, you'd have a collection that contains several sub-collections that are challenges. A challenge has all the standard stuff that a non-challenge collection has, and then a load of extra bits because it's a challenge. Does that make sense? It's not exactly intuitive, I know.
Trainee 6 That totally makes sense, and I didn't realize that was an option. Now I want to use it.
Jenny S-T Now, Testarchive. Kylie mentioned this last time in tester training, but it's quite useful for challenge stuff, too. We don't publicise it outside of the Org - it's meant for testing new code, and so shouldn't be relied on for anything else without talking to AD&T, but it's quite good for seeing how everything works. So if you're interested in trying something out there, the easiest is to speak to Kylie or anyone from AD&T, or double-check in chat. The link is http://testarchive.transformativeworks.org/
Testarchive allows you to mess around with creating fake new challenges to see how it works, without messing anything up on the actual archive, as it all gets wiped regularly. So, the easiest is going to be to look through one of the tutorials, and have Testarchive open in another window to see how it really looks - let's start with setting up a prompt meme. You can log in to Testarchive with the same username and password you use on the main Archive - it copies them across. To set up a new challenge is http://testarchive.transformativeworks.org/collections/new
When you're just playing around with stuff, the key fields are name, display title, and type of challenge - you need to pick the type of challenge when you first set up the collection - that's the only bit you can't easily change later. Once you've created the collection part, it takes you to the detailed settings for a challenge, which is the giant form of all the options in the world
Trainee 6 Oh, my gosh, that *is* giant. But it's very neat and well-organized.
Jenny S-T this is designed so you can do any type of challenge, from a small fandom-specific thing with only a few people, to something giant like Final Fantasy Exchange or the Porn Battle. It comes up with some vaguely sensible default settings, but I think the easiest is for you to ask questions at this point about what each setting actually does - some are less self-explanatory than others.
Trainee 6 Not a question -- I just wanted to note how awesome it is the TestArchive shows up in whatever skin you're using on the real archive.
AD&T Staffer 1 Yeah, all your settings get copied across. :)
Trainee 1 My question may be silly, but, how does unrevealed and anonymous work for prompt memes? Everyone is unrevealed and anonymous?
Jenny S-T you can choose - most prompt memes would set it to be anonymous but not unrevealed. Setting it to be unrevealed means that all the stories are hidden. Anonymous hides all the authors. Long-term we want to have an option for authors to choose individually whether to be anonymous or not, but for now it's decided by the mod for the whole challenge. The other way around that is to have a second collection, that stays anonymous forever, and keep the main one non-anon. Authors can choose to put their work into both collections or just one, and if you're in one anon collection and one public one, your work will be anon (except to the mods). and that's not a silly question at all :)
Trainee 1 ah, cool, thanks
Jenny S-T a kink meme would be revealed and anon, something like comment_fic would be revealed and non-anon. For a prompt meme, that form is pretty much it - you can then open it, people can submit prompts and respond to them, etc. For a gift exchange, once you've had signups, you then have all have all the options for assignments, whether you want to match people up manually or use the AO3's automated matching. It will send out all the assignment emails for you, with whatever extra info you want to add, and it will help you keep track of people who default, and any pinch hitters needed.
Jenny S-T Any other questions on either coding or challenges? We've got some time, so we can veer off topic as much as we want. And don't worry - no question is too basic or silly - someone else is probably thinking it, too, and just as unsure about asking.
Trainee 8 my question is how much training in ruby on rails you need to start making changes to the archive?
Jenny S-T very little, actually, for basic changes - things that are, say, fixing a typo, you could do with a day to read through the key bits of the tutorial. For significant stuff, people usually take a few weeks to get up to speed, if they're juggling a day job and just doing an hour or two here and there. To add a big new feature takes a year or two's experience, but there are little things that make a big difference, too. I'd done some programming before, but two years ago, I'd never heard of Ruby on Rails, and I added the prompt memes feature recently.
Trainee 2 for big features, how does collaboration work? if you write a bit of code, can someone else help finish it?
Jenny S-T usually for any big feature, there will be one main person working on it who has the code on their computer. You can share code on github and webdevs, so anyone else can view it and make suggestions. A couple of senior coders will do detailed code reviews (which is basically the same thing as a beta - catching both typos and deeper flow/structural issues). People will also bounce ideas in chat a lot.
Trainee 2 cool, thank you
Jenny S-T And yes, if you've written code and it needs fixing, we offer you first go at it, but if you need help, we can get it off your webdev and finish it off, e.g. if real life hits. You'll frequently find people in chat going "help, my code isn't working!" And if no-one's in chat at the time, you can always email the AD&T committee for help or advice.
Jenny S-T if you're keen on coding and don't have access to coders chat yet, contact Volcom, and they can sort it out
VolCom Staffer 1 note from volcom - while you can work on our code without formally volunteering, if you formally volunteer you get access to the backscroll and transcripts in the coder chatroon, which can be handy. To formally volunteer, drop your contact information into our sign up form.
Jenny S-T and feel free to email me direct if you have more questions - (address redacted to avoid spam - contact the Volunteers committee, and we'll put you in touch with Jenny!). thank you for all the questions, everyone
And that concludes our excellent session on how to code for the Archive of Our Own!