writing & communication

About

Syndication

Categories

Archives

Some Simple Rules of Argumentation

society & sociology, writing & communication

March 26, 2004, 12:04 PM

These rules of argumentation (found via Mark) are golden. They're based on the core observation that you will never change anyone's mind in a single argument, so it's a waste of your time to engage in protracted debates. The post is a little long, so I'll summarize.

When you find yourself in an argument, follow this procedure:

1. State your case as clearly, rationally, and convincingly as you can. Never re-state it; this only hurts your argument and wastes everyone's time.
2. Clarify any misunderstandings since people may disagree with your case simply because they mistook some of your points. Don't get trapped in endless clarifications, however; there's a point where the required understanding is simply based on a "you had to be there" experience and you can clarify forever and never get anywhere.
3. Walk away. For a short argument, this is easy to do without conceding defeat. Keep arguments short.

I also love the suggestion that "the ideal attitude to project during any argument is one of calm disinterest". You can't lose if you don't care about the outcome (or at least appear not to).

Those of us with better things to do can never hope to win long arguments with those who seem to have infinite time on their hands. These rules can help save time, if nothing else.

[ Permanent Location ]

Divide and Conquer

processes & methodologies, writing & communication

December 16, 2003, 04:25 PM

Now, I'm thinking about team projects and efficient ways for several people to work on the same project.

In The Mythical Man Month, Fred Brooks confronts the problem of how to effectively divide up the work of large, complex software development efforts. He concludes that the project management notion that bringing more people on to the project will linearly increase the amount of work produced is a fiction, in fact new people will actually decrease the work output temporarily as they demand the current staff's time during ramp-up. Thus, the concept of a "man-month", which assumes men and months are interchangeable, is a fiction (hence the name of the essay). Even after ramp-up, adding more people to a project exponentially increases the communication overhead, since everyone must now potentially communicate with one more person to do their job.

The key issue here is that communication cost. When working in a group, you have to consider whether its possible to split up the work in such a way that the communication costs will be low. If everyone can work in parallel without talking, then you can just divide up the work into N pieces and if it isn't going fast enough, bring in more people to make N larger. Brooks' example of a task like this is ditch digging; if your ditch deadline is bumped forward, just hire more people, give them shovels, and dig in.

Unfortunately, most kinds of thought-work, which everyone in design, usability, research, and software development tends to be engaged in, isn't very much like ditch digging in this regard. Most of our projects are communication-intensive, and can't easily be split up in such a way as to make them parallelizable. Code has to work with other code, interface designs are too holistic to develop entirely separately, research must tell a coherent story, etc. What to do?

If possible, the best answer is "do it yourself". Many novice teams make the mistake of splitting up jobs that could be done way more efficiently by any one of them alone. Don't feel like you have to give everyone an equal amount of work at the expense of making everyone work harder than they'd otherwise have to.

If the task is too big for one person to accomplish, then your best bet is radical colocation. In Agile Software Development, Alister Cockburn recommends this technique for small teams that must engage in frequent communication, and he gives an extensive argument on why even moving people down the hall from one another can drastically limit communication opportunities. This generally leads to miscommunications, which leads to buggy software, unusable interface designs, misrepresented experiment results, etc.

So in summary: if possible, don't even try to split up thought-work; have it come from one mind. If that's not feasible, try to divide it up to minimize the amount of communication the workers will have to engage in to do their jobs. If the job is such that you can't reduce this to an acceptable level (which is more often the case than not, so don't be lulled into underestimating the amount of communication necessary), then radically collocate.

The nice thing about this advice is that it applies at all levels: from units as large as corporations outsourcing large initiatives to one another and as small as two people in a small student team.

[ Permanent Location ]

Communicating Interaction

design, writing & communication

December 10, 2003, 11:10 PM

We just completed the last leg of VIID right now, having worked late into the night finishing up our last assignment (on which more will be forthcoming soon). As part of my final reflections on the class, I'd like to talk a little bit about ways to communicate interaction designs, which has been a major component of the class that we haven't talked enough about.

One of the most important (arguably the most important) parts of an interaction designer's job involves clearly and unambiguously communicating her design solutions. She must communicate to a variety of different audiences for a variety of different reasons, including:

• Other designers for getting helpful feedback in a critique. If she can't communicate clearly to her peers, then their suggestions may be muddled or inappropriate and she'll lose the many benefits of having more eyes scrutinizing her design.
• Decision makers (usually managers) for getting buy-in and go ahead with ideas. Decision makers generally want to understand the design solution she's offering before committing resources to refining, testing, or implementing it.
• Engineers for communicating what must be built. The engineers also need enough knowledge of the design rational to make micro-decisions relating to changes in the design based on development constraints.
• End users for user tests and feedback. The designer must communicate the experience well enough to collect useful data from test users, as well as to accurately gauge their reactions to the product.

The simplest way to communicate a design, and the one novice designers usually favor, is describing the attributes of the design in prose, either through talking or writing about the interactions as a flat list of features. Generally speaking, however, this isn't effective. Experience and interaction designs are inherently nonlinguistic in nature, and thus all parties need to translate back and forth between their understanding of the experience and the words they use to describe it. Even the best rhetoricians would have great difficultly expressing a nontrivial design with sufficient clarity and precision for all these purposes using words alone. So novice designers may try adding other media, such as pictures, videos, and possibly partially functional prototypes. They're on the right track, but an effective design communication can't just be a mishmash of disconnected design fragments. The designer must invest careful thought and effort into deciding the most appropriate way to communicate each piece so that they come together as a whole.

To fully understand an experience design, people must, well, experience the design. This experience needs to be as close to the final, designed experience as possible to ensure no ambiguities creep in. Keep in mind that people are very good at filling in missing details, but that they may not fill in those details in the same way the designer is. Thus, each unspecified detail is a potential point of confusion, a potential branch where the designer and the experiencer may be envisioning completely different designs. So ideally, the design should be communicated with a high-fidelity functional prototype that approximates the final, envisioned interaction experience as closely as possible.

Of course, building high-fidelity functional prototypes is very time consuming and designers need to communicate very frequently, so there's often no time to build such an artifact. What's a designer to do?

She could produce a prototype, but sacrifice the fidelity in various ways in order to make construction more feasible. When stripping away fidelity, however, she must carefully consider what communication she's losing, and whether these are critical to her communication goals. For example, a series of screen mockups done in Photoshop or another graphics tool may succeed in giving a good sense of the visual layout of the interface, but give little to no sense of how the experience of interacting with it will feel. Likewise, hand-constructed paper model prototypes may give a rough sense of the interaction but may not communicate the visual experience. Sometimes, the designer may wish to intentionally not communicate aspects of the design; if she wants to present a rough design idea and receive feedback on the concept and general structure, she may choose to use wireframes or sketches rather than full interface designs to prevent her audience from focusing on aspects of the design like color and typography which must be present, but may not be the current focus of concern.

If producing a prototype of the appropriate fidelity is not feasible, then our designer has an alternative. She may choose to develop a scenario of use (or possibly several) that depicts a typical user (perhaps one of her personas, if she's defined any) interacting with the product. This may be as simple as textual descriptions of the actions combined with the relevant screen sequences or as complex as a product demonstration movie that appears to depict an actor really using the product. Scenarios are the next best thing to experiencing the interaction design directly through prototypes; they don't let the audience really feel the experience themselves but they do allow them to observe someone else's experience. This approach may appear to be no different to the "naive" ones mentioned earlier, but in fact it is generally much more effective than a list of features or a description of disconnected interactions. Scenarios leverage the power of storytelling to effectively communicate designed experiences.

Of course, all of this advice needs to be mediated with a healthy understanding of the designer's audience and their goals. Communications will need to be tailored to the needs of the receivers; engineering will probably want to see detailed product specifications, whereas management will be more interested in projected revenues and cost justifications, for example. But the techniques in this entry can serve as general best practices to build upon for communicating any interaction design to anyone.

[ Permanent Location ]

Active Reading

teaching & learning, writing & communication

October 17, 2003, 09:59 PM

Since I came to Carnegie Mellon, and especially since I started roBlog, I've developed a new approach to reading nonfiction books and articles, both for classes and for myself. In the past, I've found that I got very little "take away" knowledge from reading papers; usually I'd remember one or two of the main points, if I was lucky. The problem, I believe, is that I was taking a very passive approach to reading; I would just sit back, scan the text, and hope to absorb the knowledge. Sometimes this works ok, but I've found a more effective way to learn.

I call it "active reading", but its basically just a matter of reading and writing about your understanding of the reading. Sometimes I try to just summarize, but often I'll reflect on the important points behind the prose, and try to connect them to other facts I've collected in the past. This serves two purposes:

1. Writing ensures I really have a complete understanding of the concepts; I won't be able to put them into words if I don't.
2. The resulting text serves as a "backup" of my reading of the article; when I inevitably forget something important, I can return to my synopsis/reflection to find it again.

On the down side, this process takes longer and consumes more energy than just sitting down and reading does alone, but I find the depth of understanding I take away from it is much greater.

[ Permanent Location ]

Posting Tool Wish List

internet, writing & communication

October 17, 2003, 09:36 PM

Micah has been pondering switching from his beloved Radio Userland to Movable Type, but has found a few of his favorite features in Radio missing in MT. In particular, he wants:

1. Rich text editing. Basically, an embedded HTML editor.
2. Automatic file uploads. I.e., you drag your file into a special folder on your local machine, and the client automatically uploads it to the server.

These sound like some pretty useful features to me. Although I love the web interface to MT (mainly because I can post from any computer) I also wouldn't mind having a more featureful local client, which is quite possible since MT supports the Blogger API. And as long as we're rattling off a wish list, I wouldn't mind seeing the following:

1. Local saving / crash protection. Sometimes I'd like to be able to write entries when I have no available network connection, so a local entry cache would be nice, but even more importantly, the tool should provide crash protection so I don't lose my posts to an application or system crash. Safari sadly lacks such a feature and I've lost more than one post to a badly-timed "unexpected quit".
2. Fix some of the annoying usability bugs in Movable Type. For instance, MT sets the posted-on date to the "first saved" timestamp, not the "first published" timestamp like I want (and which makes the most sense). Not a big deal since I can manually change it, but it's still irritating. A good tool should provide a more sensible interaction design for the posting task.
3. Spell checking. I already get this with Safari, but it's a feature I definitely don't want to lose.
4. Auto-linking certain words. Some words, like the names of my friends, I almost always link to a particular website. It'd be nice if the posting tool did this for me.
5. Smarter link management in general. I link a lot. It's what webloggers do. A good posting tool should make the process of finding and inserting links easier, perhaps through browser integration. For instance, perhaps it could help me track down references on the web for a paper or idea I'm referring to.
6. An embedded outliner. Maybe I'm the only one who does this, but I frequently outline my posts before writing them in full. A good tool should support this progression of outline-to-post in a more direct fashion.
7. Mac support. Again, maybe only I care. But I post from my Mac laptop the vast majority of the time. If a tool doesn't work on my Mac, I'm not using it. Period.

If anyone knows of a tool that implements a reasonable number of the aforementioned features, please do give me (and Micah!) a heads up.

[ Permanent Location ]

The U&SA Book Chapter

announcements, software development, usability, writing & communication

October 10, 2003, 08:10 PM

I realized I haven't been posting much recently about what I've been doing for my actual job. For those of you that I haven't yet told, I'm in the process of writing a book chapter for an upcoming book on bridging the gap between usability and software architecture. You can even check out our preliminary abstract.

The chapter is about our experiences applying our U&SA technique to the NASA MERBoard project. It looks like I'll be first author for the chapter too, which is totally awesome. The current status of the actual writing is "completed first draft". If all goes well, the final, published book will be available for purchase next September.

[ Permanent Location ]

Welcome to Wiki

internet, usability, writing & communication

October 08, 2003, 04:50 PM

I set up a Wiki last night for Dana and I to use for our CSCW project (sorry, no link to the actual Wiki; it's an invitation-only affair for now). I happened across PmWiki (which is open source) when searching for options on Wiki software (through a Google text ad, no less) and installed it to give it a shot.

So far I'm pretty happy with it, both with regards to the Wiki concept and Patrick's implementation. It's even pretty usable, all things considered, which was something I was worried about. In fact, I was browsing the documentation for PmWiki and found that Patrick had actually done some user analysis for his system. It's not quite personas, but he's definitely on the right track.

I'm hoping that the wiki will help Dana and I collaboratively distill operational design principles and heuristics from all this social science reading that we are (supposed to be) doing, thus fulfilling Bob and Paul's (and our) vision for the class. We'll see how it goes, but in any event, if you're looking to set up a wiki of your own, I'd recommend checking out Patrick's offering.

[ Permanent Location ]

Producing High-Level Documentation

software development, writing & communication

October 01, 2003, 02:00 PM

An article on Kuro5hin got me thinking about software documentation and how poorly designed so much of it is, to the point where programmers often waste weeks generating reams and reams of completely useless prose.

The author's main point is that most documentation is needlessly verbose and tends to meticulously describe the obvious or trivial details of a system's design while ignoring the important high-level design decisions that are 1) difficult to infer from merely examining the code and 2) very important for maintainers of the system to understand. As someone who's been both a developer and maintainer of software systems, I can attest that documenting architecture is important, documenting code is not.

When many programmers undertake a documentation effort, they immediately start discussing their functions and methods, describing their variables, explaining their algorithms' logic, etc. This is somewhat important up to a point, but it's frequently overdone. As Brooks states in The Mythical Man Month, systems are often produced in which the "leaves" are meticulously documented, but there is no map of the forest. When the system and its documentation are handed off to the maintenance programmer, more often than not the poor guy finds he can't see the forest for the trees.

To an extent, you can't blame these programmers for having this mentality. After all, it's what they are taught in school. In my undergraduate education, we were always graded on the existence of documentation, but we were never taught how to write effective documentation nor were we truly graded on the usefulness of our comments and diagrams to maintenance programmers. The teaching assistants generally just opened up our source files and hunted for "green stuff" (the color Visual Studio uses for source code comments), and we got full credit if there seemed to be enough.

The problem with this approach is that it produces "documentation" like the following:

/*

 * setUserID - sets the user ID

 * ID - the user ID

 */

public void setUserID(int ID) {

    this.ID = ID;

}

Anybody else see the problem here? Comments like these don't serve any purpose; they just clutter up the source code and make it harder to read, wasting both the programmer's and maintainer's time. Having documentation like this actually make things worse than having no documentation at all.

Extreme programming and agile software development are famous (infamous?) for advocating coding standards and intra-team communication over comprehensive documentation. The Pragmatic Programmers make an interesting argument in their book about the dark side of documentation; they bring up the interesting point that comments that explain code violate their DRY (Don't Repeat Yourself) principle. Essentially, explaining logic in comments counts as duplicating the logic that already exists in the code, thereby introducing a maintenance problem. Additionally, it introduces another possibility for error; if a programmer produces documentation that is ambiguous or flat out wrong it is likely to cause more confusion than no documentation would. And when documenting systems as complex as most software, such errors are inevitable.

What does need to be documented are the high-level component structures and their interactions (the architecture), the commonly recurring patterns and idioms that crop up in the system, and any important and non-obvious workaround logic ("kludges") that theoretically shouldn't be there but always seem to crop up anyway in nontrivial systems. This is most important, and should be completed before any more detailed code-level documentation effort commences. In brief, here's my thoughts on exactly what needs to be considered for documentation:

1. All high-level components and their interactions, both from a run-time and code organization perspective. This is the only part of the system that really needs highly detailed documentation since these structures define the operation of all the smaller pieces of code.
2. Common idioms that occur throughout the system, such as terminology that affects class, method, and variable names. These need to be consistent for the code to be understandable, so maintenance programmers need explicit documentation on what they are.
3. Common patterns that appear throughout the system. These may or may not appear in the high-level components, but if they are reused repeatedly they too need to be called out explicitly. Sometimes this documentation can simply point to published patterns literature such as Design Patterns.
4. Any unusual or tricky design decisions that may be unclear or misleading to maintenance programmers.

Some claim that code must be documented so that even those who are not familiar with the implementation language are able to completely understand the logic. This is silly. Someone who isn't familiar with the implementation language has no business maintaining your code (unless they are willing to learn the implementation language simultaneously with the help of appropriate reference material, of course). There may be some rare circumstances when this level of documentation is appropriate, but these are the exception and not the rule. For instance, if you are providing a sample implementation of an algorithm in a book or article and the main communication item is the algorithm itself and not its implementation, thus people who are not familiar with your chosen language must be able read and understand the algorithm as well as those who are. But in this case, I'd argue that you really shouldn't be providing a "real" implementation of the algorithm anyway; simple pseudocode would probably express the logic much more effectively.

As always, when producing a communication piece you must consider the audience and what they expect to get out of the communication. This "reader-centered document design" is a corollary of the user-centered design that I tend to advocate for anything and everything in general.

When programming, code must be the primary medium for communication; documentation must play a supporting role for expressing the ideas that cannot be expressed using code alone. The rallying cry should not be "clear code is no substitute for good documentation", it should be "good documentation is no substitute for clear code". A perfect programming language would allow you to clearly express all the important ideas, structures, idioms, and patterns to your coworkers within the language itself. Unfortunately, no modern programming language even approaches this level of capability. Until we have such a language, we must produce documentation to support and clarify our code, but it should never be viewed as the main communication medium.

[ Permanent Location ]

Note to Phone Manufacturers: Innovate!

design, writing & communication

September 03, 2003, 07:47 PM

Why is it that phone manufacturer's can't seem to create a phone that contains a single innovative, useful, and usable feature to save their lives? Even cell phones, which certainly have quite a bit of market variety (too much; I just spent ages trying to find the right one for me), don't seem to produce much real innovation. It's all well and good that the phone can synch with my address book (or so claims the box) but if I have to go through some godawful 12 step process to do it, the feature mind as well not be there. I want these features to save time, not waste it! And no, "let's stick the internet on our phone!" doesn't count as innovation.

How about adding in the ability to not ring if the caller is not identifiable? I was just interrupted from writing this very post by "Unknown Name, Unknown Number"; the fourth time tonight. Or perhaps speak the name of the caller using text-to-speech? My phone should be my ally in warding off the unwelcome telemarketers, not collaborating with them.

So come on, guys and gals. I know cell phones are new, but a little interaction design and usability would do wonders for them. And if you don't hurry up, Neema just might beat you to it...

[ Permanent Location ]

What Is It So What?

writing & communication

August 14, 2003, 12:21 AM

My bosses, Bonnie and Len, have a heuristic for writing and reviewing academic papers that Bonnie calls the "What Is It So What?" criteria. Basically, it boils down to three questions that the paper has to clearly and satisfactorally answer in order to convince the reader that the paper and the ideas it is communicating are worthwhile.

If you're bothering to write an academic paper, you're probably trying to disseminate a new idea of some sort or another, whether this idea is a new scientific theory, a technique for collecting user data, a design idiom or best practice, a novel software system to solve an important problem, etc. Even if you are primarily refuting existing ideas you are probably presenting counterideas (even if the counteridea is "idea X was wrong") and thus your paper may well fall under the same rubric. But in order to communicate this great idea, you need to make sure you address the following questions:

1. What Is It? What is the idea you're proposing? Make sure you clearly articulate what your theory states, how your technique works, or what your software system does. If people can't even grasp the idea you're proposing, they aren't going to get anything out of the paper. As usual, this means clearly and effectively communicating to your target audience by using terms and concepts they understand, referring to work they are familiar with, etc. I'd argue this is the most important part of any paper, since the other two questions are meaningless to a reader who's missed the answer to the first one. Even if you fall down on the job in later sections, at least if people understand what you're proposing they may be willing to accept it at face value. For the others:
2. Is It So? Prove it. Show me that your theory is tested, your best practice has been applied to real world projects, or your software system works as designed. Scientists, of course, are particularly skeptical people so this section is important in academia. For domains with less rigorous requirements for empirical proof, the answer to this question may contain anecdotal evidence or some form of logical reasoning. But anything is better than nothing. If you haven't had time to test your idea thoroughly yet, say so. Better to make clear what the status of your work is than be vague and make it look like you have something to hide.
3. So What? Why does anyone other than you care? If you want people to listen to you, you must convince them that your ideas can solve their problems. Ideally, give them a roadmap of how to start applying your idea today so they can see for themselves if it works. For many, all the proof in the world (see previous question) isn't comparable to being able to try out the idea and see for themselves if it works or not. Sometimes, the answer to this question is obvious. But more often, the answer to this question seems obvious to the author and is completely opaque to everyone else.

Next time you write a paper, keep these things in mind. At least if you want me to read it. :)

[ Permanent Location ]

roBlog's Scannability

internet, personal, writing & communication

August 02, 2003, 10:15 PM

Neema told me yesterday that he finds all the content on this weblog hard to digest. He suggested I provide a summary or bulleted "main points" section for each points so he could get the gist of the content without having to read the entire article.

I tend to post a lot of content on this forum because I see it primarily as a form of personal reflection and only secondarily as a form of communication. However, I'd love to improve on the second goal if there are ways of doing it without sacraficing the first, and I do realize that having several paragraphs of dense text is asking a lot from my loyal readers :). So I'm open to comments, ideas, and criticisms on how best to fix this problem.

For now, I'm trying a technique Jacob Nielsen uses on his Alertbox: he recommends highlighting important words and phrases to improve scannability. Personally, I feel this makes his essays "shout" a bit too much, but I'll give it a shot anyway. Feedback would be greatly appreciated.

[ Permanent Location ]

Photography as a Communication Medium

aesthetics, design, writing & communication

July 17, 2003, 11:29 PM

I've been learning lots of interesting things in CDF recently; sadly, since I moved last weekend and lost my broadband internet access at home for a couple weeks, I haven't had time to post about all of them. So this is my best shot at trying to play catch up.

By the end of last week, we'd finished up the photography section of the class that Charlee was teaching. Our final assignment was to combine a photograph with text to create some communication piece (Charlee likes wide-open assignments). I did a public service announcement poster type message, which I thought turned out okay, although several other people in the class put together some things that were much better, in my opinion. It was amazing to see how good everyone's was after only a week of practice and critiques.

For mine, I actually started the project intending to communicate a different message. I wanted to take a picture of an interesting but run-down street and compare it with a quote from the philosopher of art Jerome Stolnitz about the aesthetic attitude that inspired me to write Aesthetic Mornings a few years ago. But I couldn't find the right subject or the full quote, so I wound up wandering around East Liberty (a relatively poor neighborhood here in northeastern Pittsburgh) for a couple hours taking pictures of various subjects, including this bottle. At first, I wasn't too fond of any of them, but after returning home and looking at it on my screen, I decided the bottle picture wasn't too shabby, especially in black and white. But I had no idea what text to put with it. I tried a number of semi-depressing captions (I was in that kind of mood at the time) but none seemed to fit. Then I hit on "Just Another Broken Window" (a reference, possibly too obscure, to the "zero tolerance" program adopted by New Jersey in the 70s), which I thought was neat especially since the visual presentation allows you to read it as "Just Broken Another Window" as well. And so it became a public service announcement, although I couldn't quite bring myself to turn it into a just a "pick up litter" message (it seemed too trivial for the weight of the photo), so I tried to work in a larger social message as well.

I guess the point of all this rambling is that the design process is messy. Sometimes it's hard to know ahead of time exactly what you're going to wind up with, and walking into it with too precise of an idea may just end up wasting you time or (even worse) leading you away from good alternative ideas.

On a bit of a tangent, while we were doing the crit (design critique session where everyone comments on everyone else's work and suggests improvements) for this assignment we got into a discussion of how photography can be used to evoke emotions and suggest certain responses to subjects, especially when combined with text. Andy remarked that it was amazing how easy it was to misrepresent a situation you are photographing, even though you're supposedly taking a completely accurate image of the real world. There are many design variables available to the photographer, the greatest of which is the shutter itself, the box around the world through which the viewer must look. Photographers can decide what portions of the truth to show their viewers and (sometimes quite literally) what light to present them in. Thus, it is just as possible for the photographer to introduce his interpretation of reality into his work as it is for a writer or a painter to introduce theirs. But in a way this is obvious to anyone who knows anything about journalism. The interesting (sometimes dangerous) fact about photography is that it seems so real; it looks as though it is a completely accurate, objective presentation of the world. I have a suspicion that most people don't think through all this when they see a photograph; they don't ask what "spin" the photographer was trying to put on his subject as they might ask about a prose article or a painting. This makes photography a powerful medium for communication and persuasion, both of true propositions and untrue ones. It's worth thinking about the next time you're reading the morning paper.

[ Permanent Location ]