 |
« | Week of Sep 21 | < | Individual Entries | > | Week of Oct 5 | » |  |
 |
 |
Bill Joy and Language as Architecture
language, software development
October 04, 2003, 03:25 PM
I'm reading an article on Fortune's web site interviewing Bill Joy about his recent departure from Sun Microsystems. He made an interesting comment while discussing Windows' architecture:
Also, Windows isn't well architected. There's a simple way to find out if an operating system has been well designed. When you get an error message, go to the help system and look up the exact words in that message to see if there was enough of a concept of an architecture that they have a consistent vocabulary to talk about what's broken.All you have to do is try it on a Mac and on a PC to see the difference. Apple took the time to come up with a concise vocabulary, but in Windows the designers of the help system used different terminology from the programmers. That reflects a lack of design discipline, which means that as the system grows, so does the ambiguity of the software itself. The result is a system encrusted with multiple layers of things that weren't really designed in so much as bolted on.
Whatever you may think of Windows, Joy's comments ring similar to my thoughts on architecture as a shared language as well as XP's focus on metaphors instead of architecture. The bottom line is, architecture is more than just boxes and arrows; it's even more than just interacting components. Architecture is the language the development team uses to communicate, and, as Joy points out, that language better be closely aligned to the language the rest of the organization and the external users of the software use to communicate as well. Certain organizations that claim expertise in this area (but shall remain nameless) could stand to learn this lesson a little better.
Metacrap and Categories Revisited
information
October 04, 2003, 03:12 PM
I came across (Micah -> The Midnight Blog -> The Well) Cory Doctorow's essay on Metadata, entitled "Metacrap", where he outlines the reasons why the sort of universal metadata-enhanced world that information storage and retrieval experts dream of (he calls it meta-utopia) is practically impossible. Of special interest is his section on why schemas aren't natural, where he basically makes the same point I did in my post on why categories don't work so well (in brief: they are too hard to get right). He makes some interesting, true, and slightly scary points, since XML as a mechanism for universal information storage basically relies on bringing about the meta-utopia he pans.
Posted by Jordan on October 04, 2003 at 04:21 PM
Metacrap is a great essay -- makes one think about leveraging the power of groups to get to accurate metadeta -- I don't know exactly how to do this -- maybe we can learn something from wikipedia, etc.
Posted by Rob on October 05, 2003 at 10:12 AM
You might be interested in some of the things we're studying in CSCW. Unfortunately Bob axed all the readings on Recommender Systems in the interests of time, but much of the other things we're learning might also apply to ideas like this one.
Dana and I are planning to try to distill as much of the readings as we can into digestible design principles. I'll post more about that when there is more to post about.
Email Rob:
Newsable: Ready to Rock!
information, internet, software development, usability
October 04, 2003, 01:14 PM
It is, after all, Rocktober.
I've just unveiled Newsable 0.8 beta to a breathlessly-awaiting public (this public, in case you were curious, consists of Kerry and Jordan), thus marking the first release of my web-based news aggregator / modest experiment in merging open source and usability. The low-down on the current status follows.
First off, go ahead and create an account to take Newsable for a test drive. No, I really mean it. Go do that now.
Ok, now that you're back, let me confess that a few things still need work in the current release:
- The interface is ugly as all hell. Jordan is kindly lending me some of his awesome graphic design skills to help fix that. Additional help would of course be greatly appreciated.
- There are still known bugs. Namely, the harvester isn't entirely behaving itself, and the RSS autodetection algorithm needs a bit of improvement to handle the real web. I'll try to get these cleared up ASAP, but the system should be usable in the mean time.
- The help system isn't available yet. If you get confused about something, feel free to email me. This will help me know what needs documentation / usability improvements as well.
- Some of the interaction design decisions are tentative. The "Archived Stories" tab exemplifies this best. I don't yet have enough user data to make guided design decisions about these features. The personas still need some refinement.
- Some more advanced features aren't yet available. OPML import / export support is one of these. I hope to have these in place before 1.0
As you can see, there are many opportunities to get involved with improving Newsable even if you aren't interested in writing Perl code (unlike the majority of open source projects). Please email me if you have any ideas for improvements in the aforementioned areas. I may try to set up a mailing list soon to create a central place for discussion.
Happy reading!
Posted by Mathilde on October 04, 2003 at 01:21 PM
The release also consists of myself. :-) I volunteer to help Jordan with the visual design. I *need* to fix it if I am going to use it. It's *soooo* ugly right now. :-P
Posted by Rob on October 04, 2003 at 03:28 PM
Huzzah! There is benefit in doing a crappy job; it convinces others they need to give you a hand ;).
If anyone else has any interest in helping with the design or implementation of Newsable, do speak up! It doesn't even have to be anything significant; every little bit helps.
Posted by Mathilde on October 05, 2003 at 02:03 PM
Oh no! You started saying "Huzzah!" too! Curt has corrupted you. ;-)
Posted by jeff on October 05, 2003 at 07:44 PM
Congrats on the launch Rob.
Now for some constructive criticism. One long page of feed seems very hard to scan. I especially have trouble seeing the breaks between the sites.
When I order by newest, I see the newest post of the newest feed, then scroll through the entirety of the older posts of that feed before hitting the newest post of the second-newest feed. Repeat.
Since every ordering scheme except alphabetical seems to aggregate by feed, seeing breaks between feeds could significantly assist scanning.
A potential solution would be to remove the feed title from every post, and use it instead as a header that separates one feed from the previous feed. This has the added benefit of saving one line per post. Many lines over the course of the page.
Posted by Rob on October 05, 2003 at 08:16 PM
Oldest-to-newest and Newest-to-oldest actually interleave feeds, ordering entirely by Posted Time. What's probably throwing you off is that some RSS feeds don't contain Posted Time information, so Newsable has to substitute the time that it harvested the feed for the Posted Time (RSS 0.91 feeds are the offenders, in case you are curious). This means that when you first add a feed, all the posts in it are assigned the same Posted Time (the time you added it) which has the effect of aggregating them by site initially (this will change as Newsable harvests new content, though). Of course, there might also be a few bugs in Newsable at the moment that are exacerbating this problem. I'm looking into it.
Your point about site-separation is well-taken for the by-site ordering. I have an initial design idea (alternate the background gray-and-white by site, instead of by story) that should go into 0.8.1 or .2, but I like your "pull out the feed title" suggestion as well (although that'll be a bit harder to program).
Thanks for the great comments!
Posted by Jeff on October 07, 2003 at 04:27 PM
The more I understand how Newsable scrapes sites for feeds, the more impressed I become. It seems very much in the spirit of Mark Pilgrim's Ultra-liberal RSS Locator. Nice work.
Posted by Rob on October 07, 2003 at 07:56 PM
Thanks, Jeff. It turned out to be a much harder programming problem that I originally thought it'd be, given the mess that is the current state of real RSS feeds out on the real web. Conflicting standards and incorrect implementations galore.
I just came across Mark's RSS locator as well. He also has an ultra-liberal feed parser available; both of these projects are open source. Sadly, Newsable is written in Perl and thus can't take advantage of these excellent resources. Had I known Mark had done all this work for me three months ago I would have written the damn thing in Python. I hear its a cleaner language anyway.
The good news, though is that I found a Perl port of Mark's ultra-liberal RSS locator yesterday and plan to integrate it into Newsable in the next release. This should greatly improve the "Add to Newsable" functionality.
Posted by Kevin Fox on October 17, 2003 at 12:50 AM
Oooh... OPML support... I can't wait! (and I'm *not* being sarcastic!)
Email Rob:
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:
- 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.
- 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.
- 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.
- 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.
Email Rob:
An Online Community for U&SA
internet, society & sociology, software development, usability
September 29, 2003, 09:02 PM
As many of you already know, I am currently employed here at Carnegie Mellon as a research assistant for the U&SA project. By day, I investigate the relationship between the usefulness, usability, and desirability of software systems (the human-centered view) and the architectural decisions that dominate the construction of these systems and ultimately determine what is easy to change and what is hard to change (the machine-centered view). Specifically, I work to improve our U&SA technique which involves general usability scenarios and considerations that impact software architecture design decisions and design recommendations for developing architectures that better implement these scenarios. (By night, I'm either an overworked graduate student or a hard-boozin' party animal, depending on the phase of the moon and the moods of my professors...)
When I leave here, one of the projects I hope to have time to start involves developing an online community for improving and refining the U&SA technique. Essentially, I believe we've got something good here but that it could benefit from more industry feedback and the infusion of best-practice wisdom. Hopefully CSCW will better prepare me for this task by the end of the semester, but in the meantime, here's a few thoughts on what such a community might look like:
- The scenarios could go in a wiki so that several people could propose and refine examples of architecturally-sensitive usability issues. This way, every time someone encountered an important usability concern that turned out to be difficult to add later and that wasn't covered by our material, they could add a scenario for it or modify an existing scenario to include it.
- Discussion boards on applying the scenarios to real-world projects and technologies. These boards may focus on discussing technology-specific patterns for the scenarios, such as implementing Cancel in a J2EE system, or on existing toolkit and framework support for the scenarios.
- Moderated essays on distilling out considerations and patterns from the scenarios and technology discussions. These essays would necessarily entail a lot of meta-analysis and require a higher degree of accuracy, so they should require more community consensus for publication. I'm thinking something like a Kuro5hin-style voting system for determining whether they're published or dumped.
So those are my initial, very rough ideas. If you're interested in helping me flesh them out some time, please do let me know.
Email Rob:
Email Rob: