Archive : July 2007

On the use of “user”

Elyse Sanchez, Monday, July 30, 2007 @ 11:40 am

“I’m sick of users,” announced Josh Bernoff in
a recent blog entry, leading one to initially believe that he has joined the
ranks of indifferent (or outright hostile) developers, clients, and other uninterested
parties reluctantly associated with producing applications and websites. However,
Bernoff’s distaste is semantic, not social. He argues that the term “user”
emphasizes technology over relationships and encourages a flattened and skewed
view of the people interacting with the products. He challenges the readers to “try,
just for a day, to stop using this word. You’ll be amazed at how differently
you think about the world.”

 

 

Continue reading »

User Experience Design User Experience Design

When is an Ajax Framework Worth Mentioning

Dietrich Kappe, Monday, July 30, 2007 @ 5:45 am

I'm getting a bit more selective in which Ajax frameworks and libraries I give more than a passing thought. There are just too many of them out there, like weeds after the desert rain. For a framework to be worth attention, it has to have at least one of the following going for it:

  1. Unusually clever; something new.
  2. Extremely well executed, small and focused.
  3. A complete solution, soup to nuts, with widgets, OO utils, Ajax utils, package management, etc.
  4. Something that supports agile development, e.g. TDD focused

I'm sure we're all familiar with the FURPS acronym (Functionality, Usability, Reliability, Performance, Supportability). The last one, "supportability," is an important one that often gets overlooked. Essentially, how difficult or expensive will the system be to support over time? So perhaps there is a fifth reason, supportability. That may be hard to gauge in a marketplace of libraries and frameworks that is changing so quickly; a framework that is hot today may be supplanted or abandoned tomorrow. So how about a proxy: a framework that developers are absolutely gaga over?

One of the soup to nuts frameworks I haven't mentioned previously is Ext JS. What is Ext JS? From the FAQ:

Ext is a client-side, JavaScript framework for building web applications. In early 2006, Jack Slocum began working on a set of extension utilities for the Yahoo! User Interface (YUI) library. These extensions were quickly organized into an independent library of code and distributed under the name "yui-ext." In the fall of 2006, Jack released version .33 of yui-ext, which turned out to be the final version of the code under that name (and under the open source BSD license). By the end of the year, the library had gained so much in popularity that the name was changed simply to Ext, a reflection of its maturity and independence as a framework. A company was formed in early 2007, and Ext is now dual-licensed under the LGPL and a commercial license. The library officially hit version 1.0 on April 1, 2007.

So, an extension of YUI, but now it's own thing. Even better, Ext JS runs on top of other Ajax libraries and you can pick your favorite one, Prototype, YUI or JQuery.

Touching back to the supportability discussion above, there are some things to like here:

  • They are backed by a commercial company, offering open source and commercial licenses.
  • They have a large and enthusiastic developer following.
  • They have a growing footprint among large companies.
  • They are a soup to nuts framework, with basic Ajax and DHTML utils all the way to complete widgets.
  • Lots of documentation and tutorials.

And then there is the enthusiasm factor. All of the developers I've talked to are absolutely gaga about Ext JS. Gaga. That, to me, is a higher recommendation than any feature list. However you feel about Ruby on Rails, the framework has had a salutary effect on development frameworks in general. With it's transformation into a product and services company, few people remember that 37signals started out as a user experience design (UXD) company. They used to be our competition in Chicago. ;-) It took a UXD company to focus on providing good user experiences to developers, not just end users. So, if you're an aspiring framework designer, keep user experience in mind for your developers. What will make their life easier. Maybe then developers will love your framework as much as they love Ext JS.

Now a little sample of Ext JS. Just a simple data grid. The data and layout are handled through different pluggable behaviors. Nice.

I'll have a few more things to say about Ext JS, along with it's use with DWR and AIR.

Technorati Tags: ,

Topics: ,

Software Development Software Development

Second Story: Walking the Walk

Elyse Sanchez, Friday, July 27, 2007 @ 1:38 pm

Second
Story Interactive Studios, in its own words, “creates informative and
entertaining interactive experiences in the form of media-rich storytelling
presentations, online collections, interpretive installations, and
database-driven applications.” The company comprises a diverse team of creative artists,
writers, producers, animators and programmers who enjoy a work environment that
boasts both a screening room and a technology lab for experimentation,
prototyping and testing of their projects.

 


Continue reading »

User Experience Design User Experience Design

This is Important: Tamarin in IE and Bytecode Translation

Dietrich Kappe, Thursday, July 26, 2007 @ 8:48 am

So, a short while ago I wondered what the future of Ajax would be if Javascript ran great in Firefox, but like crap in IE. Well, the Mozilla guys are at it again. Check out this report on the Ajax Experience West keynote over at Ajaxian.com.

Mozilla is taking IronPython and IronRuby produced from Microsoft and mapping it to to Tamarin. This will by in the guise of bytecode translation a la IKVM as they want to avoid forking C# source using Mono C# compiler.

Direct to bytecode, baby! The fact that I predicted this is proof that you don't have to be a genius to predict these things. ;-)

Even more exciting is the Screaming Monkey project, which aims to have Tamarin running in other browsers as a <script> tag handler, including IE. Yes! Fast Javascript everywhere. Still, I hear the voice of Bill Gates whispering in my ear, "DOS ain't done til Lotus won't run." (Is it a myth? Se here.)

Technorati Tags: , , ,

Software Development Software Development

A Sequence Diagram for Scriptaculous

Dietrich Kappe, Thursday, July 26, 2007 @ 7:47 am

In reverse engineering the Scriptaculous into GWTaculous, I've done a bit of spelunking and produced a few artifacts to explain Scriptaculous to myself. I thought I'd share one of them -- a sequence diagram for Effects -- in the hopes that someone else will find it useful. The diagram below isn't complete -- it doesn't contain the event calls -- and it doesn't cover the Parallel effects, but it does give a decent overview for anyone trying to understand the Event lifecycle or someone trying to write their own effect.

Technorati Tags: , ,

Software Development Software Development

The JavaRanch GWT in Action Review

Dietrich Kappe, Thursday, July 26, 2007 @ 5:51 am

After reading a comment at Ajaxian on my GWT in Action review, I thought I'd mosey on over to the JavaRanch to read their, presumably, harsh review and see why I had totally missed the boat on this book. Well, not so harsh, as it turns out:

I felt that the book was trying to reach too broad an audience. For beginners without an understanding of JavaScript/HTML/DOM, I think it is overwhelming. The book provides "what's new in GWT 1.4", but the book is overkill for someone already using GWT. Most of the time the book treats what happens under the hood of GWT as magic and other times it becomes important. This switching of focus is a bit confusing.

Fair enough. Would this book be on point for a beginner? Maybe not. It's hard for me to say, since I'm not really a beginner in all of these domains. The book is trying to hit a broad audience, and from the preface (since I've started reviewing books, I always read the preface) they say they are targeting everyone from JavaScript developers, to Java server-side developers, to web designers. They add that the reader should have a good understanding of Java classes and packages. That seems to narrow it down to Java developers again. Unlike the authors, I don't think that Java and the use of Eclipse is something you can just sort of pick up as you read along.

Still, I do think the book is a good one. This is not just another Java package or framework; this is a whole new way of writing apps in the browser and the subject is expansive and complex. The book just reflects that -- it isn't just 600 pages of pictures, white space and padding. Could the examples have been more useful and relevant to typical webapp developers? Sure. I point that out in my review, but even with that flaw, I found the book very useful. And in all fairness, focusing on implementing a full-on Spring/Hibernate backend to the GWT app would have easily doubled the size of the book, larded in lots of unnecessary technologies, and given the critics (many of whom are disgruntled JavaScript programmers) even more ammunition.

Some readers will have noted that publish generally positive reviews. That's not because I'm a shill for the publishers, but rather that I put really awful books down pretty early in the process. Generally, books for which I end up publishing reviews are interesting and worth reading. For bad books, I could summarize my review in one sentence: don't waste your time. I guess maybe I should publish a list of the tech books that suck; that could be a long list.

Technorati Tags: , ,

Topics: ,

Software Development Software Development

Review of GWT in Action

Dietrich Kappe, Monday, July 23, 2007 @ 5:48 am

Any time a hot technology comes along -- and GWT is certainly white-hot -- publishers compete in a mad scramble to get the first books out the door. Often quality suffers. I am happy to report that GWT in Action is a strong effort that doesn't seem to suffer from this quality problem. (That isn't to say there aren't any errors and omissions in the book, just no obvious ones that I've found in my reading of it.) Instead, the book offers a solid, learn-by-example approach to understanding the Google Web Toolkit.

This learn-by-example approach, tied together through the development of a dashboard application over the course of several chapters, strikes, I think, the right balance for a broad audience. This is not the reference "bible" for GWT, though it does contain more reference material in one place than any other source so far, so you'll have to wait for that sort of reference work. But for anyone wanting to get a jump start on GWT, start developing applications, and understand what all the fuss is about, I heartily recommend this book.

The book is organized into 17 chapters, split into four parts: Getting started; Building user interfaces; Advanced techniques; Completing the understanding. So, on to what's in the book, chapter by chapter:

  1. Introduces you to the central ideas of GWT: compiling Java in JavaScript and debugging in Java. Does a good job of touching on most of the features of GWT -- widgets, internationalization, JRE emulation library, RPC, browser history, etc. -- and illustrating them with code samples. Finishes off with a complete client-side (no RPC) tic-tac-toe example app.
  2. Things slow down a bit here, as the authors delve into the organization of a GWT project and the details of the GWT development cycle. I'm torn on whether this chapter could have been illustrated more clearly with an example application, rather than just by enumerating the steps and components and diagrammatically illustrating the work-flow. The information that's here is solid and correct, but the approach seems to conflict with the learn-by-example used so well in the rest of the book.
  3. Begins the process of developing the Dashboard application -- essentially a web desktop or portal with draggable component apps. It makes concrete the more abstract development life cycle notions of the previous chapter. At the end of this chapter you have a skeleton application with menus,
    a trash icon and some basic CSS styling, and you will have run it (and debugged in Eclipse for hosted mode) in
    both hosted and web mode. This chapter attempts to instill good behavior by adding i18n ("internationalization" with the 18 letters between the "i" and the "n" omitted) at the very beginning. That way if you leave it our of your apps, you have no one to blame but yourself. You'll also have a good understanding of the major project files: the HTML file, the EntryPoint, and the module XML file.
  4. The start of Part 2 of the book which introduces GWT "widgets" -- in short, GUI components. Dissects their dual nature as Java objects and DOM elements and introduces the basic GWT widget set. Covers several common GUI and Web concepts, such as DOM events, focus, keypresses, etc. Shows two different ways of developing custom widgets -- one from scratch by manipulating the DOM and the other, the PNGImage to support transparent PNG's in IE6, by extending an existing widget class. Finishes off by building the first two custom widgets for the dashboard application, the TwoComponentMenuItem and the ToggleMenuItem. The full details of building the PNGImage class, using GWT's technique of deferred binding to handle browser differences, is split between here and Chapter 15. Small nit: I think the concept is important enough to have merited a section of its own in this chapter or the other.
  5. Presents the basic concepts of GWT panels -- the containers that hold widgets and other panels. If you know Swing, this will all seem pretty familiar, in particular DeckPanel, FlowPanel and DockPanel should seem familiar. (It is interesting to note that in GWT, layout is specified through inheritance (Is A FlowPanel), while in Swing it is a pluggable behavior (layout manager).) Of course, remember to pay no attention to the HTML Table behind the curtain, at least not if you want your code to keep working when the implementation changes. The chapter finishes off by extending DialogBox to a DashboardPanel that can be used and manipulated in a multi-window interface (or MDI).
  6. Focuses on Events, both Browser/DOM events and it's custom Widget events. This is a long chapter (over 50 pages) and covers lots of territory. If you already know your way around Java and the various kinds of Listeners, you've won a quarter of the battle, but you may want to brush up on the browser side of the equations a little bit before reading it (see here, here and here). Not that the chapter doesn't do a good job of presenting the material, but sometimes you need to have a firm grasp of one topic before combining it with another, and I think this is definitely one of those times. The chapter finishes off by implementing drag-and-drop for the Dashboard app, combining the widget knowledge from the previous two chapters with your new understanding of events.
  7. Composite widgets are again old hat if you have experience with Swing. Basically you combine existing widgets into "mega" widget. This chapter illustrates the concept by walking your through the implementation of three composite widgets: EditableLabel, ColourPicker (Colour=Color, for the Yanks in the audience), and the DashboardComposite framework class.
  8. Introduces JSNI (JavaScript Native Interface), essentially a way of fooling your IDE and the Java compiler into ignoring embedded JavaScript in your GWT code, while allowing the GWT Java to JavaScript compiler to make use of it. Demonstrates wrapping the Google Video and Ajax search libraries with JSNI.
  9. Gets into the nitty gritty of how GWT modules are put together. Essential if you are going to build reusable libraries and components that can be included in GWT applications. Really, this is where you start to find out about the inner workings of GWT, the XML, the JavaScript, etc. This chapter could stand to be a bit more in-depth. Don't skip over it in any case.
  10. The start of Part 3 of the book -- advanced techniques. Introduces GWT-RPC, i.e. the GWT abstraction over XMLHttpRequest. Make sure you have a firm grasp of XMLHttpRequest before you delve into this chapter (see here and here). Again, it helps to be well versed in the basics when something new is introduced. The chapter does a good job of explaining perhaps one of the more confusing bits of the GWT -- two execution environments (client and server), three Java classes, Sync, Async, callbacks, and the IsSerializable interface. Also show how to use the typeArgs annotation to give hints to the GWT compiler (not something you usually see in online tutorials).
  11. Digs into the client-side part of RPC. Offers patterns for simplifying the GWT-RPC code through the Facade, Singleton and Command patterns. Examines ways to implement both server pull (GWT-RPC polling) and push (blocking server threads, but see also GWT and Comet - Using GWT with Jetty Continuations). Also explains custom field serializers -- needed for some complex objects or objects that don't implement IsSerializable or have a zero argument constructor.
  12. Covers the more traditional ways of doing Browser/Server communication, with the traditional XHR style RequestBuilder, parsing the returned XML data with XMLParser, and traditional postback with FormPanel.
  13. Introduces JSON (JavaScript Object Notation) and the GWT classes that support it. It wouldn't hurt to review the basics of JSON a bit more here, but it's not quite as important as in chapters 6 and 10. Demonstrates its application through use of the Yahoo Search API. Shows how to use JSON to integrate with Java, Perl and Ruby on the server. The latter examples are fairly simple, but they give you enough to start rolling your own. (FYI, you can also do JSONP with GWT.)
  14. GWT generators are a compile-time mechanism for generating new classes based on parameters (used from JUnit, logging, RPC, etc.). Builds on the module knowledge from chapter 9. This chapter gets deep into the inner workings of the compiler. As it turns out, you can do introspection in GWT, but only at compile time.
  15. Gets into various runtime and compile-time parameterization of GWT apps, specifically i18n, constants, dynamic constants (client side associative arrays) and browser specific code. This is where you have to go to understand exactly what you did with the PNGImage class.
  16. The start of Part 4 of the book. Covers a number of topics: JUnit and GWT, testing async code and deploying GWT apps on the client and server sides. The JUnit and async testing piece really should be a chapter on its own. The section on deploying GWT apps points out many of the hidden pitfalls packaging up an app, such as the old or unused files generated during development that need to be removed for a slim package.
  17. This chapter is the natural continuation of chapters 9 and 14. It delves even deeper into the inner workings of GWT, such as the compilation process and the generated and static JavaScript files that make up an application. It also gives a quick tutorial on how to diagnose problems on the client side using the PRETTY and DETAILED styles of JavaScript output.

The book does cover many of the new features in GWT 1.4, such as Image Bundling, the new loading mechanism, and the Serializable vs IsSerializable changes. Some of the new widgets, such as the Rich Text Editor, are not covered, however.

As I've said, overall a fine effort. I do have three issues with the book, however. First, there is no mention of the incompatibility between GWT and IE7. Since much of the world's population still uses IE7, that's a major oversight. It would have been nice to at least mention the hack to UserAgent.gwt.xml to make it work for IE7. The other issue is that the rich UI sample Dashboard application really deserved a transactional companion, i.e. some sort of app that illustrates how GWT would function with a more substantial server-side app. That may be a little too much to ask of one book that tries to introduce so many new concepts and ideas already, and there are some online tutorials that provide just that sort of example.

the Finally, testing with JUnit is relegated to the penultimate chapter of the book. Software development is momentum and habit. If you start off developing without unit tests, you will have a hard time incorporating it into your process later on. Testing should have been presented in the first chapter and used throughout in each subsequent chapter, so as to givereader a good grounding in JUnit and GWT.

Still, the three issues certainly don't detract enough from the book to change my overall opinion: definitely read this book.

Technorati Tags: , ,

Topics: ,

Software Development Software Development

The iPhone experience

Sholom Sandalow, Saturday, July 21, 2007 @ 1:10 am

The iPhone has finally arrived, and I’ve been playing around with it here and there.  What can I say; it’s another example of the degree to which Apple’s fanaticism with user experience pays off.  As soon as I held it in my hands, I knew that it was going to be fun, just plain fun, to use this thing.  How many mobile devices can you say that about.  The only ones that come to mind are the gaming devices, Sony PSP, Game Boy, Nintendo DS.  I don’t know of any other mobile phones that are actually fun to use.

Two things struck me as key differentiators between the iPhone and the dozens of equivalent products – Smart Phones, PDA’s, etc..--on the market:

First, Apple’s obsession with simplicity is abundantly clear in this device, like none of it’s previous products.  This is a culmination, or at least a progression.  In a sea of complexity, it seems like they understand modern humanity’s longing for the simple better than anyone, and by a wide margin.  The company is quickly becoming the definition of simple technology.  Their latest product has only one physical button.  Everything else is software.  And the software is so simple and inviting, that I’d feel completely confident giving it to my grandmother to use to make a call, or even watch some video, without any instructions.

Also, it’s the little things—the details that would somehow get overlooked in most software—where the iPhone really shines.  Things like, the way the screen moves naturally with your finger and comes to a smooth stop—unless your at the end of the scrollable region, in which case it ‘bounces’ up against the edge of the display.  Or the way one screen pleasantly fades into the next.  Or the way you never seem to need to do any thinking when going from step to step in any process, like sending an email, or sorting you music list.  They’ve taken a huge advance in touch screen technology, and, through obsession with user experience, created a true revolution.  In anyone else’s hands the iPhone would just be cool, in Apples hands it becomes a paradigm shift.

User Experience Design User Experience Design

Google Maps Component for Echo2

Dietrich Kappe, Thursday, July 19, 2007 @ 6:30 am

Just stumbled across this not quite ready Google Maps component for Echo2 over at Sourceforge. Hacim Bengalis over at his blog has taken this work and presents the code changes necessary to getting it to work with Echo2. Basically, he registers his own service (i.e. the stuff that gets run at start time for an Echo2 session, as I recall) that injects the Google Maps Javascript include into the page.

    /* add google maps api */    baseDoc.addJavaScriptInclude("js/googleload.js");

If you read French, then this fellow claims to have done it without having to register his own services, i.e. with a stock Echo2.

The solution use the component HttpPaneEx from EchoPointNG (I guess this is standard library for most Echo2 users). This component creates an HTML Iframe in which you can display any HTML pages : even one using GoogleMaps. Next, you need to interact with it. The trick is to use method enqueueCommand and JavaScriptInclude and JavaScriptEval object from Echo2 to trigger javascript from Echo2.

I recall that when I tried this with Echo2 2.0.x, I had issues with the Echo2 client engine capturing events and making the Google maps component do weird things. His tutorial looks extensive; anybody feel up to translating some French?

Technorati Tags: , ,

Topics: ,

Software Development Software Development

Informagen Echo2 Component Library

Dietrich Kappe, Thursday, July 19, 2007 @ 6:16 am

Will Gilbert has contributed a handful of validating form field components. Take RegExTextField, for instance. It will take a regex and, surprise, validate the input against it. Maybe not earth shattering, but handy nonetheless.

Technorati Tags: , ,

Topics: ,

Software Development Software Development

Another Echo2 Sample App

Dietrich Kappe, Thursday, July 19, 2007 @ 6:05 am

Kenneth Riggio has put together an Echo2 sample app -- a single player Blackjack game.

He was kind enough to put up his source code and even gave a hat tip to my getting started tutorial.

Technorati Tags: , , ,

Topics: ,

Software Development Software Development

GWTaculous Grows a Little More

Dietrich Kappe, Thursday, July 19, 2007 @ 5:30 am

GWTaculous keeps plodding along a little more. I've got the Parallel effects base class done and am working my way through the simple effects. Highlight and Move are done and Scale is up next.

I've got the original effects on the left hand side for comparison. I'm finding that I have to pull some of the style effects out of Prototype.js. I'm stuffing them in a DOMX class (with the whole browser specific DOMXImpl tree) for possible reusability. I'm not sure of all of the choices I've made there, but that's what refactoring is for.

I've also discovered that the GWT parseDouble() and parseFloat() are not like the Javascript parseFloat(). The Javascript one will slurp up any old crap and try to spit out a number. The Java/GWT variety will barf on invalid strings. One look will tell you why:

public static double parseDouble(String s) throws NumberFormatException {    return FloatingDecimal.readJavaFormatString(s).doubleValue();}

The GWT version isn't simply a wrapper around the Javascript version. Yes, this sort of precision in language and library can cost time, but it also avoids errors. Anyhow, lesson learned. Now my Move doesn't go back to the starting point with each click.

Technorati Tags: , , ,

Topics: ,

Software Development Software Development

Writing Technical Requirements: The Third Commandment

Scot Witt, Tuesday, July 17, 2007 @ 10:45 am

Use Cases, User Stories, Functional Specification, Functional Decomposition, ad nauseum

These are all requirements developers, managers, QA and Technical Writers use at various points in the software development life cycle. Whatever you're writing, for whatever purpose, you need to keep it clear, it needs to be concise and it needs to be understandable to more than one audience.

This blog is a show by a couple of examples and comments rather than pithy items you can use immediately.

Here we go with the third Technical Requirements Writing Commandment:

III. Care for Use Cases and Make Them Fruitful to
Multiply

Let's use Use Cases as the example- they can be used in Waterfall and disciplined Agile. You write them like an in-depth User Story and Functional Specifications often include the really high level Use Cases.

Here's an okay example from Alastair Cockburn:

Scope: ATM
Level: User Goal
1. The card gets inserted.
2. The card information gets validated
3. The transaction information gets collected and validated
4. The cash is issued, card returned, cash removed, account debited and screen reset.

The Good:

  • Simple wording
  • Only four steps
  • other than 'validated,' most people will understand this
  • Nicely organized with nice grouping to reduce the number of steps.

So what are Scot's beefs with this one?

  • I have no Use Case Title, Number or Context.
  • The Actor (person or system performing the action) is never identified.
  • There's no goal- you can infer it in Step #4, but I need to  know that before I start and so does my developer.
  • I like step-action tables- the left column tells me what the actor's done and the right column tells me what happens.  That way, we all know what's happening.
  • There's no error handling.
  • Passive Voice (ugh!)- tell me who's performing the action, please!

An okay Example, but improvable.

Here's a really bad one from Cockburn:

(Withdraw Cash) (WEUC)

1. Customer runs ATM card through card reader
2. ATM reads the bank ID and account Number
3. ATM Asks customer whether to proceed in English or Spanish
4. Customer selects language
5. ATM asks for PIN Number and to press ENTER
6. Customer enters PON number and presses ENTER
7. AT presents a list of activities for the Customer to perform
8. Customer selects "withdraw cash"
9. ATM asks customer to say how much to withdraw, in multiples of $5 and to press Enter
   (it just continues like this)

The Good:

  • There's a title.
  • I can infer the goal from the title- the bad is I shouldn't have to infer anything).
  • I assume WEUC has something to do with the numbering or classification system. More than what I had above, but not really good yet.

The Bad:

  • I fell asleep at step 5.
  • When was the last time an ATM actually talked to you?
  • Am I the only person who understands PIN Number= Personal Identification Number Number?
  • Where does the Customer do all these selecting acts?
  • What exactly is this really cool list of 'activities?'

Our second example raise more questions than it answers. If I were the BA in a traditional shop, I would expect to be answering questions for a week on this. If I were working on an Agile Team, I'd split this into several User Stories for Customer review.

This use case also demands a long series of business rules.

While writing use cases, specifications and the like, consider organizing them, numbering systems and the like. Your readers need to be able to find stuff quickly and your PM needs to track your progress.

In future blogs, I have some thoughts on wikifying the process.

Stay tuned.

Next Up: Commandment IV. Business Rules Made Simple.

Technologies and Platforms Technologies and Platforms

Writing Technical Requirements: The Second Commandment

Scot Witt, Tuesday, July 17, 2007 @ 10:00 am

In our first installment, we found out it's important to know your audience and help your audience by using some common sense rules. Today, Knowledge is King. The second Technical Requirements Writing Commandment is:

II. Know of Which Yea Speak, Lest Your
Reader Will Know Yea for a Fool.

This is the second rule of writing. If you do not
completely understand the subject matter, your reader will know you don;t know it within a sentence or two. Here's how to avoid this trap:

  •   Find SMEs (Subject Matter Experts) both for the System and the Business

       -Recognize and ask the questions you need to ask so you understand.
       -Make a VISIO diagram- shows gumption and you have something physical to change
       -Do the research- the internet and existing documentation can help frame and provide background

  • · Never ever feel your questions are stupid- if
    you have a question, it cannot possibly be stupid.

       -Well, if you're a consultant it might sound stupid to the customer.
               * Phrase it to get their buy in- "Help me out here...<insert Question>"
               * Look like you're struggling- "I'm having a lot of trouble with <insert Question>
               * If you don't understand the answer, rephrase it,
re-address the issue by relating it to                     something you already know

  • Use the Web. Google is a wonderful and greatly
    used tool for Business Analysts and technical writers. You can use it, too.

Consider what process you're starting with your requirements:

  1. Gather- interviews, document reviews, project documents, research
  2. Organize- outline, lists, numbering systems
  3. Write- get it on paper or the wiki
  4. Review- get revisions from SMEs and Team Members
  5. Publish- In waterfall environment, this is the sign-off, in agile it's start of the feature
  6. Revise- changes-

Now think about what your reader brings to the table:

  • At least one goal
  • Years of experience
  • Years of education

Anyone can hide behind long words, buzzwords, jargon and some irrelevant graphics. But the folks who need the material you're providing have extremely limited time and patience.

If you can't explain your topic in simple, easy to digest words, you don't understand it.

Next Up: Use Cases

Technologies and Platforms Technologies and Platforms

Writing Technical Requirements: The First Commandment

Scot Witt, Monday, July 16, 2007 @ 10:24 am

Business Analysts seem to come from two areas:

  • Developers who want to be Writers
  • Writers who want to be Developers

Coming from the second group myself, I've often been asked to help neophyte writers improve their skills. Trading writing tips for tech points is a good thing for me since I can abstract and write from today until tomorrow- but unless I understand what I'm writing about, it's more than obvious. Hence my 'quickie writer's course, the Ten Commandments to Writing Technical Requirements.

Here's the First Commandment:

I. Thou Shall Always
Address the Audience's Needs

You have three major audiences for and Requirements
Documentation:

  • · Developers/IT Professionals
  • · Business and Project Managers
  • · Quality Assurance Staffers

Each audience has a different educational and experiential background and their own jargon.

To address each audience's needs, follow these guidelines:

1. Eliminate
jargon. You may know what SQL means,
but the VP of Order Management may not and you do not want to make that person feel inadequate nor do you really want to explain what SQL is- I usually say 'queries the database' and leave it at that.

2. Clearly
and effectively organize and label the elements of your document. We'll get into this very important area in a future blog, suffice it to say here you can get a big head start by:

       - Splitting your material into logical groups your reader can easily understand

       - Properly labeling each group so your reader can scan the doc to find what s/he wants.

       - Use an outline- revise the outline when needed, but use it.

3. Use
consistent terms and phrases throughout the document. Don't call it 'The Application' in one are and 'The System' in another. pick one and stick with it.

4. Eliminate
buzzwords. Don't use 'initiate' when you mean 'start.' Don't use 'terminate' when you mean 'end.' And, one of my pet peeves- 'entitle' is not a fancy word for 'title.' If you are entitled to something- it means you deserve or earned it.

5. Avoid
clauses. If you need to use one, put it at the beginning, but not in the middle since the reader can't parse it that well, or end of a sentence, if you use one clause in a sentence you can put it at the end, but that should be your second choice. See what I mean?

6. Avoid
passive voice- see Commandment V. For now, just remember "Boy paints the fence" is ACTIVE voice and "The fence was painted by the boy" is PASSIVE. Note both sentences  mean exactly the same thing. It has nothing to do with verb tense, it has to do with who's doing what in the sentence.

7. When
using the command form, use "must," not "shall."
"Shall" is regal and antiquated. Better yet- ignore all those 'The System must....' statements entirely and just start writing after the word 'must.'

Writing is organized thought. If you can design it, you can
write it. Write it as though you were explaining it in a conversation with your
non-technical parent. Except my mother. Ain't no way that'll happen. In such a case, you do not talk down to them,
but try to make them understand. 

This is the first rule of any writing.

Next Up: Knowledge.

Topics:

Technologies and Platforms Technologies and Platforms

Launch: Pathfinder Newsletter

    Get a monthly update on best practices for delivering successful software.

    Subscribe via email


    Subscribe via RSS      RSS icon

Categories

Topics

Blogroll

Search

WordPress

Comments about this site: info@pathf.com