The Joel Test : Part 1

There's a software engineering blog I have read on and off for a while, found here:

http://joelonsoftware.com/

A fellow at my work recently retired, and left some books behind.  Among them was a book by this same guy (Joel Spolsky) called "Joel on Software".  I was particularly interested in an article both present in the book and at the following link, called "The Joel Test: 12 steps to Better Code" :

http://www.joelonsoftware.com/articles/fog0000000043.html

It outlines 12 litmus-type tests that, according to him, indicate the health and productivity of a software development team.  I'm planning on following most of this advice with my own team, and have already implemented some of it (though some parts remain).  I'll discuss the first 6 tests here, and the latter 6 in a later post.

#1: Do you use source control? 

    This kind of seems like a no-brainer for a team project to me.  I've never done a team project without some kind of source control tool.  Sounds like a friggin' nightmare.  For this project, my team is using Git in conjunction with BitBucket.

#2: Can you make a build in one step?

     I feel as though this test will be a challenge to implement for us.  We are using several different technologies, including a remote MongoDB instance, Java code in conjunction with the Play web framework, and web stuff like HTML, CSS, and Javascript for the front end.  I intend to insist we can pass this particular 'Joel test'.  If we need some list of 15 things to re-bundle and create the software project, that's gonna stress everyone out and bog us down near the finish line.

#3: Do you make daily builds?

     I actually don't think this one applies to us as much.  For one, this project is not a full-time job for us, so daily builds are not really necessary.  However, I do think that once we are settled into our basic code base and our making improvements and adding features to it, weekly or bi-weekly builds would be nice.  Note that this test can really only be feasible if you can pass test #2.

#4: Do you have a bug database?

   This is a tool that we had not discussed before I brought up this article to the team.  I have seen bug-tracking programs in action, and have become a believer in them.  I was originally going to use a separate one (e.g. 'Buggle'), but it was pointed out to me that our BitBucket has a built-in system.  We'll see if that does the job when we get deeper into development.

#5: Do you fix bugs before writing new code?

     I will demand this from the team as much as possible.  If you're trying to add features on top of buggy code, you might as well be building a skyscraper on quicksand.  You'll also burn time debugging things that are the fault of already-buggy code, rather than the new code.

#6: Do you have an up-to-date schedule?

     We are currently failing this test, in my opinion.  Our schedule and milestones are evolving so rapidly that the written version is simply inaccurate.  I will be working to fix this soon.

Tests 7-12 to come in a later post.

Client meeting reaction and project log (week of 2/23)

Our client meeting went MUCH better this time, or at least it felt that way to me.  Since our last one, we did some soul searching and had some important conversations on design and implementation plans.  This time we also had documents to back up our story - we had a more complete user story with a website mockup from Sonny, Alan provided a detailed description of the graph search we intend to use, and I provided a comparison summary of the database systems I had researched.

Going forward, we are trying to make some skeletons and prototypes.  Alan is going to write his basic setup to perform greedy graph search on diagnostic charts with edge weights (as well as managing and updating those edge weights when solutions are reported by the user).  David is going to stand up two web frameworks, Django (Python) and Play (Java/Scala), so he can compare them.  Sonny is going to provide us a basic website like the one his mockup depicted.  Finally, I am going to stand up a remote MongoDB database and work with Alan on a schema for it which will play nicely with his component of the system.  The database will store diagnostic procedures and information about which causes from those procedures are the most likely (i.e. are reported most often).

I feel a bit better about the status of our project than I did last week.

Some musings on databases and the NoSQL vs. SQL debate

So I've been doing some research into what kind of database this project will use for the knowledge base component.  There may be a separate database for managing user accounts, which is a much simpler functionality.  The short of it is that I'm thinking MongoDB is a good fit...

One of the main things I've been trying to decide is whether we want to do SQL or "NoSQL", and what are the real strengths and weaknesses of those two 'classes' (if you want to call them that).  Note that NoSQL actually stands for "Not Only SQL", and some NoSQL databases have SQL-like query languages but use different representations and organization for data.  What I'm generally finding (and have seen this in limited experience with systems such as MySQL) is that SQL databases, or more generally relational databases, are not all that good at encoding graphs nor hierarchical objects.  This is a natural weakness from the explicit use of tables as the fundamental concept.  Also, there's often a disconnect between how most object-oriented programs represent data and how that can and is represented in a relational database; this difference is sometimes called "impedance mismatch".

On the other hand, I'm liking what I find about NoSQL databases, and in particular document-oriented databases such as MongoDB.  Instead of rigid tables and pre-defined schemas, a document database stores data in formatted files, which can be plain text but are often binary for efficiency.  There is, of course, a syntax to these documents but there are generally not rigid requirements on what each object must or must not contain.  This kind of flexibility allows similar objects to store things if they need them and omit them if they don't.  I find this strength to be in direct contrast to the column concept in SQL-type database systems.  You often see those types of database tables with some columns that are usually NULL - this is either because most records simply don't need or have that data, or designed into the schema in the beginning and remains because it's harder to remove it than to keep storing all those NULL's.

A key aspect of this decision is that we will have some complex data structures in the database.  Per the work Alan Kuntz is doing, we will be storing graphs in this database representing diagnostic procedures with edge weights reflecting frequency of problem occurrence.  I am deeply concerned that using a relational database for this purpose will cause us nothing but heartache and pain.  By contrast, I believe a procedural step object (node) in a system like MongoDB could look something like this (pseudocode of course):

object node_step
{ "instructions": "check X"                                 // what's displayed to the user
   "id": "12345"                                                   // a key into this object
   "connected": "12678,78912,56742"                // connected nodes, could also point to Edge objects
   "value": "0.45"                                                // frequency of occurrence (based on repair history)
}

By contrast, I'm not all that sure how this would look in a relational database like MySQL.  I guess we would have a table for node_step, with the columns shown above, and the field "connected" would be a set of numbers (there may be an inherent flexibility about the number of connections right there) that are foreign keys into other entries in node_step.  To me, that document-oriented style just seems so much more suitable.  MongoDB uses BSON, a binary encoding of JavaScript Object Notation (JSON).  JSON is a language-independent data format that plays nicely with Java, Javascript, and many other languages.  The format of JSON is basically like that node_step object above.  I am feeling like the choice of this technology is a critical one because this knowledge base is essentially the core functionality of this application.

What it's like to have your project picked

It's both a great and a worrying feeling.  Questions start rushing through your head.  Do I actually know what I'm doing?  Is my proposal doable?  Is this team going to complete the job with me at the mast?  I'm hoping the answer to all of these questions is YES.  I feel grateful that I think I've been assigned a good team.  I believe the guys in my group are solid.  I won't let 'em down.

To Mechanapp!

Final project selections

Well, I did it.  I made my final project selections.

Thinking back on it, this was a pretty cool road that got us here.  We all had to cook up an idea, define and refine it, and try to sell it to each other.  I'm genuinely impressed at what some people came up with, and I'm excited (and a bit nervous) to see what gets picked and where I get assigned.  I'll admit that most of my project picks were heavily influenced by the presentations.  A notable exception to that was Automaton, a proposal for a computer science educational game by Luke Balaoro.  His presentation was good, but not quite enough to make me note-to-self to go read his proposal.  I ended up reading it anyway, and wow.  Good stuff.  I hereby give the 'best overall proposal' award to Luke.  It was really well-written, gave a lot of solid detail, and seems like an interesting idea.  I didn't rank it highest in my preferences only because I'm not sure how much I want to work on a game this semester (don't think it's really my forte).

Good luck to everyone on the vote next week.

Thoughts on pitches and effective 'project marketing'

So we wrapped up our project pitches today.  I think mine was good, but there's that usual lingering feeling that I could have been better prepared and organized for it.  I'm noticing something interesting as I go to narrow my preferences for project assignment down to 5: the in-person pitches I've heard over the last couple days are a surprisingly strong influence to that process.  As I watched these presentations, I was noting projects I found interesting to further research and consider for my preference list.  I've grazed through the relevant proposals, but found myself looking at ones I hadn't noted to pursue during class time.  What I'm finding is that some of those 'edge' projects are actually quite interesting, and a couple of them are possible candidates in my list.  It's kind of funny to note how much a two-minute speech can sway you for or against a project in comparison to a detailed 15-pager.  I suppose the speech format is more effective at manipulating our emotions (i.e. "do I like you?  do I believe you can lead this project"), while the actual proposal paper appeals more to our logic and reasoning (i.e. "he seems to have everything planned out well").

Proposal Review for Brandon Lites

Review of proposal: "Ambient Algebra"

Proposal author:  Brandon Lites

(blog: http://blitescs460.blogspot.com)

Reviewer: James Vickers (jvick3@unm.edu)

Proposal restatement

         The proposal is to make a set of mini-games which teach college students algebra concepts when played.  The project seeks to address high failure rates in college math courses and low proficiency of students.  The games will be accessible online and the site will track user progress and provide facilities for leaderboards and achievements for players.

Reviewer reaction

         As a former math tutor at CAPS, I know first-hand many of the problems this article discusses.  Many students are not motivated to learn math early on.  They actually can get quite interested if the topics are presented to them in more relevant ways.  I think educational games are a good way to do this, if they can be made appealing enough for college-age students.  I, like many others, have learned skills from games.  I learned to type at a young age by playing educational typing games.

Quantitative scores

Format: 4

            Overall, the format is good.  I would consider trimming down the previous work section.  Some of the information included there does not appear relevant to the proposal.  The budget and timelines could be nicer (the budget should probably be in a spreadsheet or table rather than the way it's displayed).

Writing: 4

            The writing style is clear and concise, but the paper needs a proofread and polish - some sentences are missing words or have the wrong word if you read them aloud.

Goals and tasks: 4

            The timeline lists each member for 3.5 hours for the first two weeks, but at least 10.5 hours per person for each subsequent week.  Sounds like a risky slow start to me.  Otherwise, the timeline and its milestones seem reasonable.  I like how the timeline has a min-max range for hours worked each week.

Scope: 3

            Project is stated to be a supplement to mathematics instruction throughout the proposal.  However, at one point it is stated that "Ambient Algebra is designed to replace a student's homework in which they solve problem after problem".  I think this single statement may be a dangerous overreach of scope for this project.  This would likely cause backlash from universities, and it may not be best for students to practice for exams and quizzes in a totally different format (game vs. on paper).

Plausibility: 5

            Project appears perfectly feasible, and the author clearly identifies the technologies to be used.  There is, of course, a serious challenge to be had in making a game both fun and educational.  I think this may be amplified by the fact that the game is targeted for college-age students; I think marketing may be a key factor in getting these students to want to play games of this nature.

Novelty:  3

            Early in the article you say that, of existing educational math games, there are "none in which learning algebra is the secondary motivation of playing the game" (page 2).  Later, on page 4, you go on to say that "there are websites that offer games to teach algebra".  As a reader, I read the first statement as a claim that no game websites for math education existed (which I was skeptical of).  The second statement acknowledges the other games and explains the differences between them and your proposal.  The main novelties of the idea are a different target audience (college-aged instead of grade-school aged) and the use of leaderboards and achievement tracking.  It's not clear to me if the second novelty exists elsewhere already.

        

Stakeholder identification: 2

            Students (the main users) are identified as the major stakeholder.  The United States as a nation is sort of an implicit stakeholder in the article, through the discussion of its dismal test scores.  I think more should be said about some other key stakeholders, namely universities (who may suggest the site for students or even make donations of time/money to it) and people or groups that sponsor students (such as scholarship foundations or parents).

Support and impact: 3

            The project will charge a fee of $10 per semester for access.  The budget section of the proposal claims that "With around 1400 students taking this course each semester, we can assume a revenue of $14,000 dollars per semester."  I find this statement way too optimistic.  You can hardly expect every kid in a math class to buy the correct version of the textbook and a calculator as it is.  This claim also forgets that the problem it seeks to address (high failure rate of these classes) will also work to invalidate this projection - many students drop in the first 2-3 weeks from a lack of motivation or self-confidence.  The pricing model suggested may or may not be appropriate, as similar educational game websites instead collect revenue from advertising and do not charge their users any fees.

Evidence:  4

            Your motivation section (II) is SOLID.  Giving stats on the failure rates of early algebra classes at UNM and the relative scores of the nations of the world really highlights the issue your project seeks to address.  The budget could perhaps use a little more break-down and thought.  For example, programmers are going to be paid $35 per hour (when the national average is more like $45), and the workstation for the project manager costs twice as much as for a team member (though it's not clear why that is).

Challenges and risks: 4

            The main challenge discussed is making games that are both fun and educational.  Another one mentioned is making sure the games are relevant to common areas of struggle for students.  The only gave this section a 4 because I think another one exists that should be mentioned: convincing instructors to get over biases they may have about educational games so they may recommend this one for their students.