Writeup

part of Software Engineering for Internet Applications by Eve Andersson, Philip Greenspun, and Andrew Grumet
If I am not for myself, who is for me?
When I am for myself, what am I?
If not now, when?
-- Hillel (circa 70 B.C. - 10 A.D.)


If I do not document my results, who will?
If the significance of my work is not communicated to others, what am I?
If not now, when?
-- philg
Do you believe that the world owes you attention? If not, why do you think that anyone is going to spend thirty minutes surfing around the community that you've built in order to find the most interesting features? In any case, if much of your engineering success is embodied in administration pages, how would someone without admin privileges ever see them?

In code reviews at the beginning of this class, we often find students producing source code files without attribution ("I know who wrote it") and Web pages without email signatures ("nobody is actually going to use this"). Maimonides's commentary on Hillel's quote above is that a person acquires habits of doing right or wrong—virtues and vices—while young; youths should do good deeds now, and not wait until adulthood. I.e., if you don't take steps to help other users and programmers now, as a university student, there is no reason to believe that you'll develop habits of virtue post-graduation. An alternative way of thinking about this is to ask yourself how you feel when you're stuck trying to use someone else's Web page and there is no clear way to send feedback or get help or how much fun it is to be reading the source code for an application and not have any idea who wrote it, why, or where to ask questions. Continuing the Talmudic theme of the chapter, keep in mind Hillel's response to a gentile interested in Judaism: "That which is hateful to you, do not do to your neighbor. That is the whole Torah; the rest is commentary. Go and study it."

A comment header at the top of every source code file and an email address at the bottom of every page. That's a good start toward building a professional reputation. But it isn't enough. For every computer application that you build, you ought to prepare an overview document. This will be a single HTML page containing linear text that can be read simply by scrolling, i.e., the reader need not follow any hyperlinks in order to understand your achievement. It is probably reasonable to expect that you can hold the average person's attention for four or five screens worth of text and illustrations. What to include in the overview illustrations? In-line images of Web or mobile browser screens that display the application's capabilities. If the application supports a complex workflow, perhaps a graphic showing all the states and transitions.

Here are some examples done by folks just like yourself:

In case you're looking for inspiration, do remember that if Microsoft, Oracle, Red Hat, or Sun products either worked simply or simply worked, half of the people in the information technology industry would be out of jobs. Also keep in mind that for every person reading this chapter a poor villager in India is learning SQL and Java. A big salary can evaporate quickly. Between March 2001 and April 2004 roughly 400,000 American jobs in information technology were eliminated. Many of those who had coded Java in obscurity ended up as cab drivers or greeters at Walmart. A personal professional reputation, by contrast, is a bit harder to build than the big salary but also harder to lose. If you don't invest some time in writing (prose, not code), however, you'll never have any reputation outside your immediate circle of colleagues, who themselves may end up working at McDonald's and be unable to help you get an engineering job during a recession.

Exercise 1

Prepare an overview document for the application that you built this semester. Place the document at /doc/overview on your server.

Try to make sure that your audience can stop reading at any point and still get a complete picture. Thus the first paragraph or two should say what you've built and why it is important to this group of users. This introduction should say a little something about the community for whom the application has been built and why they can't simply get together in the same room at the same time.

It is probably worth concentrating on screen shots that illustrate your application's unique and surprising features. Things such as standalone discussion forums or full-text search pages can be described in a single bullet item or sentence and easily imagined by the reader.

If you find that your screen shots aren't very compelling and that it takes 5 or 6 screen shots to tell a story, consider redesigning some of your pages! If it makes sense to see all the site's most important features and information on one screen in your overview document, it probably makes sense for the everyday users of the site to see them on one screen as well.

You have two basic options for structure. If it is more or less obvious how people are going to use the service, you might be able to get away with the Laundry List Structure: list the features of the application, punctuated by screen shots. In general, however, the Day-in-the-Life Structure is probably more compelling and understandable. Here you walk through a scenario of how several users might come to the application and accomplish tasks. For example, on a photo critique site you might show the following:

  1. Schlomo Mendelssohn uploads his latest photograph of his dog (screen shot of photo upload page)
  2. Winston Wu views a page of the most recently submitted photos and picks Schlomo's
  3. Winston uploads a comment on Schlomo's photo, attaching an edited version of the photo (screen shot of the "attach a file to your comment" page)
  4. Schlomo checks in from his mobile phone's browser to see who has critiqued his photo
  5. Winona Horowitz calls in from a friend's telephone and finds out from the VoiceXML interface that a lot of new content has been posted in the last 24 hours
  6. Winona goes home to a Web browser and visits the administration page and deletes a duplicate posting and three off-topic posts (screen shot of the "all recently uploaded content")
  7. ...
You can work in all of the site's important features in such a scenario, while giving the reader an idea of how these features are relevant to user and administrator goals.

Note how the example above works in the mobile and VoiceXML interfaces of the site. All of your readers will have used Web sites before, but mobile and VoiceXML are relative novelties.

What Do We Mean by "Professional"?

What do we mean by "professional"? Does it even make sense in the context of software engineering? The standard professions (law and medicine) require a specific educational degree and certification by other professionals. By contrast, plenty of folks who never took a computer science course are coding up a storm in Java right now. Nor has their work in Java been evaluated and certified by other programmers. In theory, if your incompetence kills enough patients, your fellow physicians can prevent you from practicing medicine anymore. If you steal too much from your clients, your fellow lawyers are empowered by the state to prevent you from working.

Without a required educational program or state-imposed sanctions on entry to the field, what can it mean to be a "professional programmer"? Let's take a step back and look at degrees of professional achievement within medicine. Consider three doctors:

Most of their fellow physicians would agree that Surgeon 3 is the "most professional" doctor of the group. Surgeon 3 has practiced at the state of the art, improved the state of the art, and taught others how to improve their skills. Is there a way for a programmer to excel along these dimensions?

Professionalism in the Software Industry (circa 1985)

As the packaged software industry reached its middle age around 1985, it was difficult for an individual programmer to have an impact. Software had to be marketed via traditional media, burned onto a physical medium, put into a fancy package, and shipped to a retailer. Consequently, fifty or more people were involved in any piece of code reaching an end-user. It would have been tough for a software engineer to aspire to the same standards of professionalism that put Surgeon 3 over the top. How can the software engineer ensure that his or her innovation will ever reach an end-user if shipping it out the door requires fifty other people to be paid on an ongoing basis? How can the software engineer teach other programmers how to practice the innovation if the software is closed-source and his or her organization's employment agreements mandate secrecy?

The industrial programmer circa 1985 was a factory employee, pure and simple. He or she might aspire to achieve high standards of craftsmanship, but never professionalism.

What were a programmer's options, then, if in fact craftsmanship proved to be an unsatisfying career goal? The only escape from the strictures of closed-source and secrecy was the university. A programmer could join a computer science research lab at a university where, very likely, he or she would be permitted to teach others via publication, source code release, and face-to-face instruction of students. However, by going into a university, where the required team of fifty would never be assembled to deliver a software product to market, the programmer was giving up the opportunity to work at the state of the art as well as innovate and teach.

Professionalism in the Software Industry (circa 2000)

There is some evidence that standards are shifting. Richard Stallman and Linus Torvalds draw crowds of admirers worldwide. These pioneers in the open-source software movement are beginning to exhibit some of the elements of Surgeon 3 (above): The Internet makes it easier for an individual programmer to distribute work to a large audience, thus making it easier to practice at the state of the art. The open-source movement makes it easier for an individual programmer to find a job where it will be practical to release his or her creations to other programmers who might build on that work.

It is thus now within a programmer's power to improve his or her practice as a software engineering professional, where the definition of professional is similar to that used in medicine.

A Proposed New Definition

Suppose that we define software engineering professionalism with the following objectives:
  1. a professional programmer picks a worthwhile problem to attack; we are engineers, not scientists, and therefore should attempt solutions that will solve real user problems.
  2. a professional programmer has a dedication to the end-user experience; most computer applications built these days are Internet applications built by small teams and hence it is now possible for an individual programmer to ensure that end users aren't confused or frustrated (in the case of a programmer working on a tool for other programmers, the goal is defined to be "dedication to ease of use by the recipient programmer").
  3. a professional programmer does high quality work; we preserve the dedication to good system design, maintainability, and documentation, that constituted pride of craftsmanship.
  4. a professional programmer innovates; information systems are not good enough, the users are entitled to better, and it is our job to build better systems.
  5. a professional programmer teaches by example; open-source is the one true path for a professional software engineer.
  6. a professional programmer teaches by documentation; writing is hard but the best software documentation has always been written by programmers who were willing to make an extra effort.
  7. a professional programmer teaches face-to-face; we've not found a substitute for face-to-face interaction so a software engineering professional should teach fellow workers via code review, teach short overview lectures to large audiences, and help teach multi-week courses.
Could one create an organization where programmers can excel along these seven dimensions? In a previous life, the authors did just this! We created a free open-source toolkit for building Internet applications, i.e., something to save customers the agony of doing what you've just spent all semester doing (building an application from scratch). Here's how we worked toward the previously stated objectives:
  1. committing to attack the hardest problems for a wide range of computer users; niche software products are easy and profitable to build but most of the programmers on such a product are putting in the 10,000th feature. Our company simultaneously attacked the problems of public online community, B2B e-commerce, B2C e-commerce, cooperative work inside an organization, cooperative work across organizations, running a university, accounting and personnel (HR) for a services company, etc. This gave our programmers plenty of room to grow.
  2. staying lean on the sales, account management, user interface, and user experience specialists; a programming team was in direct contact with the Internet service operator and oftentimes with end-users. Our programmers had a lot of control over and responsibility for the end-user experience.
  3. hiring good people and paying them well; it is only possible to build a high-quality system if one has high-quality colleagues. Despite a tough late 1990s recruiting market, we limited ourselves to hiring people who had demonstrated an ability to produce high-quality code on a trio of problem sets (originally developed for this course's predecessor at MIT).
  4. giving little respect to our old code and not striving for compatibility with too many substrate systems; we let our programmers build their professional reputation for innovation rather than become embroiled in worrying about whether a new thing will inconvenience legacy users (we had support contracts for them) or how to make sure that new code works on every brand of RDBMS.
  5. having a strict open-source software policy; reusable code was documented and open-sourced in the hope that it would aid other programmers worldwide.
  6. dragging people out to writing retreats; most programmers say that they can't write, but experience shows that peoples' writing skills improve dramatically if only they will practice writing. We had a beach house near our headquarters and dragged people out for long weekends to finish writing projects with help from other programmers who were completing their own writing projects.
  7. establishing our own university, assistant teaching at existing universities, and mentoring within our offices; a lot of PhD computer scientists are reluctant to leave academia because they won't be able to teach. But we started our own one-year post-baccalaureate program teaching the normal undergraduate computer science curriculum, and we were happy to pay a developer to spend a month there teaching a course. We encouraged our developers to volunteer as teaching assistants or lecturers at universities near our offices. We insisted that senior developers review junior developers' code internally.
How did it work out? Adhering to these principles, we built a profitable business with $20 million in annual revenue. Being engineers rather than business people we thought we were being smart by turning the company over to professional managers and well-established venture capital firms. In search of higher profit, they abandoned our principles and, in less than two years, turned what had been monthly profits into losses, burning through $50 million in cash. The company, by now thoroughly conventional, tanked.

In short, despite the experiment having ended rather distressingly, it provided evidence that these seven principles can yield exceptionally high achievement and profits.

Exercise 2

Write down your own definition of software engineering professionalism. Explain how you would put it into practice and how you could build a sustainable organization to support that definition.

Final Presentation

In any course using this textbook, we suggest allocating 20 minutes of class time at the end of any course, per project, for a final presentation to a panel of outsiders. Each team then has an opportunity to polish its presentation skills to an audience of decision-makers, as distinct from the audience of technical peers that have listened to earlier in-class presentations.

Young engineers need practice in convincing people with money to write checks that will fund their work. Consequently, the best panelists are people who, in their daily lives, listen to proposals from technical people and decide whether or not to write checks. Examples of such people include executives at large companies and venture capitalists.

We suggest the following format for each presentation:

  1. elevator pitch, a 30-second explanation of what problem has been solved and why the system is better than existing mechanisms available to people
  2. demo of the completed system (see the "Content Management" chapter for some tips on making crisp demonstrations of multi-user applications) (5 minutes; make it clear whether or not the system has been publicly launched or not)
  3. a slide showing system architecture and what components were used to build the system (1 minute)
  4. discussion of the toughest technical challenges faced during the project and how they were addressed (2 minutes; possibly additional slides)
  5. tour of documentation (2 minutes) — you want to convince the audience that there is enough for long-term maintenance
  6. the future (1 minute) — what are the next milestones? Who is carrying on the work?
Total time: 12 minutes max.

Notice that the technical stuff is at the end. Nobody cares about technology until they've seen what problem has been solved.

Lessons from MIT

From observing interaction between our students and panelists at MIT, a few consistent themes have emerged.

Panelists love documentation. They've all seen code monkeys and they've all seen running programs. Very seldom in their lives have they seen clear and comprehensive documentation. We've seen senior executives from Microsoft Corporation get tears in their eyes looking at the documentation for a discussion forum module. The forum itself had attracted a "seen it before" yawn, but the executives perked up at the sight of a single document containing a three-paragraph overview, the SQL data model, a page flow diagram, a list of all the scripts, some sample SQL queries, and a list of all the helper functions.

Panelists need to have the rationale for the application clearly explained at the beginning. Otherwise the demo is boring. Practice your first few minutes in front of some people who've never seen your project, and ask them to explain back to you what problem you've solved and why.

Decision-makers who are also good technologists like to have the scale of the challenge quantified. The chief information officer from a large enterprise wanted to know how many hours went into development of the application that he was seeing and how many tables were in the data model. He was beyond the point in his career when he was writing his own SQL code, but he knew that each extra table typically implies extra cost for development and maintenance.

You need to distinguish your application from packaged software and other systems that the panelists expect are easily available. Don't spend five minutes showing a discussion forum, for example. Every panelist will have seen that. Show one page of the forum, explain that there is a forum, that there are several levels of moderator and privacy, and then move on to what is unique about what you've built. After one presentation, a panelist said "Everything that you showed is built into Microsoft Sharepoint". A venture capitalist on the panel chimed in "If at any time during a pitch someone points out that there is a Microsoft product that solves the same problem, the meeting is over."

At the same time, unless you're being totally innovative, a good place to start is by framing your achievement in terms of something that the audience is already familiar with, e.g., Yahoo! Groups or generic online community toolkits and then talk about what is different. You don't want the decision-maker to think to herself "Hey, I think I've seen this before in Microsoft Sharepoint" and have that thought in her head unaddressed the whole time.

Decision-makers often bring senior engineers with them to attend presentations, and these folks can get stuck on personal leitmotifs. Suppose Joe Panelist chose to build his last project by generating XML from the database and then turning that into HTML via some expensive industry-leading middleware and XSLT, plus lots of Java and Enterprise Java Beans. This approach probably consumes 100 times more server resources than using Microsoft Visual Basic in Active Server Pages or a Perl script from 1993, but it is arguably cleaner and more modern. After a 12-minute presentation, no listener could have learned enough to say for sure that a project would have benefited from the XML/XSLT approach, but out he comes with the challenge. You could call him a pinhead because he doesn't know enough about your client and the original goals, e.g., not having to buy a 100-CPU server farm to support a small community. You could demonstrate that he is a pinhead by pointing out large and successful applications that use a similar architecture to what you've chosen. But as a junior engineer these probably aren't the best ways to handle unfair or incorrect criticism from a senior engineer at a meeting, especially if that person has been brought along by the decision-maker. It is much better to flatter this person by asking them to schedule a 30-minute meeting where you can really discuss the issue. Use that 30-minute meeting to show why you designed the thing the way that you did initially. You might turn the senior engineer around to your way of thinking. At the very least, you won't be arguing in front of the decision-maker or appearing to be arrogant/overconfident.

To the Panelists

Imagine that each student team was hired by your predecessor. You're trying to figure out what they did, whether to fund the next version, and, if so, whether this is the right team to build and launch that next version.

As a presentation proceeds, write down numerical scores (1-10) for how well a team has done at the following:

Following a team's 12-minute presentation, tell them what they could have done better.

Don't be shy about interrupting with short questions during a team's presentation. If the presentation were from one of your subordinates or a startup company asking for funds and you'd interrupt them, then interrupt our students.

Parting Words

Work on something that excites you enough that you want to work 24/7 on it. Become an expert on data model and page flow. Build some great systems by yourself and link to their overview documents from your resume — be able to say "I built X" or "Susan and I built X" rather than "I built a piece of X as part of a huge team".

More

Time and Motion

The writeup should take four to six hours and may be split among team members. An effective division of labor might be: screen shot technician, writer, proofreader. Thinking about and writing down a definition of professionalism ought to take one to two hours. The presentation will go faster if the team has kept up with their documentation, but ought to take no more than a few hours to prepare plus an hour to practice a few times.
Return to Table of Contents

[email protected], [email protected], [email protected]