opensource.google.com

Menu

Melange:Tips and Tricks for Users

Wednesday, February 13, 2013


What happens when you “lock” 4 engineers and 4 program managers in a room together for 5 days? Besides a bunch of coffee cups, empty energy drink bottles, and a variety of healthy and non-healthy snack remnants, you get two books written to help users of Melange, the open source software that administers the Google Summer of Code and Google Code-in programs.

In January, Melange developers and members of the Google Open Source Programs Office (OSPO) collaborated on two books that we hope will help users of Melange understand the many functionalities of the software. The main purpose of this document sprint (by day 4 it was more like a marathon), was to help prospective students and open source organizations use the software efficiently and to its fullest capacity. All of us in OSPO also learned a ton about using the software as Program Administrators.

Our terrific facilitator, Adam Hyde of Floss Manuals, started the week off early Monday morning with a lengthy brainstorming session with well over a hundred post-it notes scattered on whiteboards in various categories. We started to see how the sections of the book would evolve and then we organized the post-its into our potential chapters. Then the writing began, and boy, did we write! The book is designed not only to answer questions, but to be a step-by- step guide for each role a person might encounter when using the Melange software. We created dummy accounts and took screenshots so that we could see everything a person in that particular role (mentor, student, organization administrator or program administrator) would see.


The first couple of days were spent writing, reading over each other’s work and adding to each other’s sections. When you have 8 people writing different parts of a book you end up with considerably different tones and many style questions.  One large whiteboard was covered with style decisions that we all agreed on, from whether to capitalize “Student” every time it was used to when to use italics versus quotes.

Throughout the week we posed questions to each other and filed bugs on software and UI issues. By Wednesday we had a pretty solid book that then needed to have copy edits and some additional screenshots added.  While part of the group worked on the edits and tweaks some of the Melange engineers worked on fixing many of the bugs and UI issues uncovered.
Having Melange engineers and users (OSPO team) in the same room going through the process from the student, mentor, organization administrator and program administrator perspective was enlightening to say the least.  The engineers were able to explain some features that we didn’t realize worked in a certain way, we all talked through bugs and additional ideas for features, and having the engineers working alongside us to fix and implement these ideas was awesome!

The Open Source programs office has hosted 2 other document sprints with the Floss Manuals team in the last 15 months but this was the first time we were the ones heads down with our noses to the grindstone.  The book sprint process is not for the faint of heart but having a solid book on our software that users can refer to (and the writers too!) is extremely satisfying and a great way to start off the new year.

If you are interested in the finished products you can view them online:  Melange - Google Summer of Code and our Melange - Google Code-in manuals. While you’re there, check out the other manuals that Adam and his team have helped create. Your project could be next!

By Google Open Source Programs team
.