Writeup

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.

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:

Winston Wu views a page of the most recently submitted photos and
picks Schlomo's

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)

Schlomo checks in from his mobile phone's browser to see who has critiqued his
photo

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

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")

...

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:

Surgeon 1 does the same operation over and over in a Beverly
Hills clinic and makes a lot of money.

Surgeon 2 is competent in all the standard operations, but in
addition has developed an innovative procedure and, because of the
time devoted to innovation, makes less money than Surgeon 1.

Surgeon 3 has developed an innovative procedure and practices it
regularly, but also makes time for occasional travel to France, China,
Japan, and Argentina to teach other doctors how to practice the
innovation.

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):

they practice at the state of the art, writing computer programs
that are used by millions of people worldwide (the GNU set of Unix
tools and the Linux kernel)

they have innovated; Stallman having developed the Emacs text
editor (one of the first multi-window systems) and Torvalds having
developed a new method for coordinating development worldwide

they have taught others how to practice their innovation by
releasing their work as open-source software and by writing
documentation

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:

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.

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").

a professional programmer does high quality work; we
preserve the dedication to good system design, maintainability, and
documentation, that constituted pride of craftsmanship.

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.

a professional programmer teaches by example; open-source
is the one true path for a professional software engineer.

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.

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:

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.

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.

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).

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.

having a strict open-source software policy; reusable code
was documented and open-sourced in the hope that it would aid other
programmers worldwide.

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.

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:

elevator pitch, a 30-second explanation of what problem has been
solved and why the system is better than existing mechanisms available
to people

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)

a slide showing system architecture and what components were used to
build the system (1 minute)

discussion of the toughest technical challenges faced during the
project and how they were addressed (2 minutes; possibly additional slides)

tour of documentation (2 minutes) — you want to convince the
audience that there is enough for long-term maintenance

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:

This team has communicated clearly what problem they've solved.

The demo gave me a good feeling for how the system works.

This team has done an impressive job tackling engineering challenges.

This team has documented their system clearly and thoroughly.

I'd really like to hire these people for my own organization.

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