- We design and build extraordinary applications for companies looking to make the next great idea a reality.
- learn more
On the use of “user”
“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.”
When is an Ajax Framework Worth Mentioning
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:
- Unusually clever; something new.
- Extremely well executed, small and focused.
- A complete solution, soup to nuts, with widgets, OO utils, Ajax utils, package management, etc.
- 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.
Topics: Ajax Frameworks, Javascript Libraries
Second Story: Walking the Walk
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.
This is Important: Tamarin in IE and Bytecode Translation
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: ajax, tamarin, ie, firefox
A Sequence Diagram for Scriptaculous
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: ajax, scriptaculous, gwtaculous
The JavaRanch GWT in Action Review
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: ajax, book review, gwt
Review of GWT in Action
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:
- 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.
- 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.
- 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. - 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.
- 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).
- 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.
- 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.
- 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.
- 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.
- 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).
- 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.
- 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.
- 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.)
- 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.
- 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.
- 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.
- 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: ajax, gwt in action, book review
The iPhone experience
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.
Google Maps Component for Echo2
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: ajax, echo2, google maps
Informagen Echo2 Component Library
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: ajax, echo2, components
Topics: Ajax Components, Echo2
Another Echo2 Sample App
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: ajax, echo2, games, examples
Topics: Ajax Frameworks, Echo2
GWTaculous Grows a Little More
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: ajax, gwt, scriptaculous, gwtaculous
Topics: Ajax Frameworks, GWT
Writing Technical Requirements: The Third Commandment
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.
Writing Technical Requirements: The Second Commandment
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:
-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:
- Gather- interviews, document reviews, project documents, research
- Organize- outline, lists, numbering systems
- Write- get it on paper or the wiki
- Review- get revisions from SMEs and Team Members
- Publish- In waterfall environment, this is the sign-off, in agile it's start of the feature
- 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
Writing Technical Requirements: The First Commandment
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: Web/Tech
About Pathfinder
Recent
- Implementing linked multiselects with jQuery, LiveQuery, and Low Pro: Part 1: Requirements and interaction design
- Many Varied Components, or… Multi Variable Complexity, or… Mainly Vanilla Coding
- Custom Flex 3 Lightweight Preloader with source code
- Mass Assigning Inheritance Column Values for ActiveRecord STI with Rails
- Working effectively as a team of one: Five tips for front-end developers on Agile teams
- Ruby on Rails with Windows - How I made it work
- Project Website Part 5: Morph in 11 steps or so
- Papervision3D 2.0 (Great White) in Flex 3 (Part II & III combined) with source code
- What’s In Your Dock?
- Why Chicago is Rails-town, USA
Archives
- August 2008
- July 2008
- June 2008
- May 2008
- April 2008
- March 2008
- February 2008
- January 2008
- December 2007
- November 2007
- October 2007
- September 2007
- August 2007
- July 2007
- June 2007
- May 2007
- April 2007
- March 2007
- February 2007
- January 2007
- December 2006
- November 2006
- October 2006
- September 2006
- August 2006
- July 2006
- June 2006
- May 2006
- April 2006
- March 2006
Topics
.NET
3d
3D GPS
Accessibility
actionscript
activerecord
Add new tag
ADO.NET Entity Framework
Adobe
Adobe AIR
Advertising
agile
Agile Development
AIR
Ajax
Ajax Applications
Ajax Bookmarking
Ajax Components
Ajax Development
Ajax Examples
Ajax Frameworks
Ajax Intervention
Ajax libraries
AJAX Obfuscation
Ajax Performance
Ajax Products
Ajax Tools
Ajax Widgets
Analysis
Android
Announcement
Announcements
antennae
Apollo
Application Architecture
Application Development
ASP.NET
Asynchronous Processing
awards
Back Button
Benchmarking
Best Practices
BitmapData.draw
BJAX
Blaze Advisor
blog
blogging
Books
Browsers
Business Reasons for Ajax
Business Rules
C#
Canvas
Case Studies
Chicago
CMS
COBOL
Code Generation
Color
COMET
Conference
Consistency
Content Management
CRM
CSS
Custom Flex Component
Degrafa
Design
Design Patterns
Desktop
Desktop RIA
Developer's Notebook
Diagnose
Dojo
Domain Knowledge
Drools
Echo2
Echo3
Editorial
ERP
Ethnographic Research
Ext JS
Facebook
FileReference
Firefox
Firefox Extensions
Flash
flash awards
flash player 10
Flex
flexunit
Flow
Frameworks
front end
front end development
Games
Gauge Component
Google
Google calendar
Google Gears
Grails
Graphics
Greasemonkey
Groovy
GStreamer
Gwittir
GWT
Healthcare
Hibernate
IDE
Ideation
IE
IE6
IE7
IE8
ILOG JRules
Information Architecture
Innovation
Instructional Design
Interaction Design
Interview
iPhone
iTunes
Java
Javascript
JavaScript frameworks
Javascript Libraries
JBoss Rules
Jess
Jetty
Jobs
jQuery
JSF
JSON
JSR-94
Lazlo
Legacy Systems
lightweight
LinkedIn
LINQ
Logical Model and Conceptual Model
Low Pro
Mac
Mash Note
Mashups
MetaWidget
Methodology
Microformats
Microsoft
Mobile
Mootools
Mozilla
Music
MVC
MySql
Object-Oriented
Object Relation Mapping (ORM)
Office
OOP
Open Screen
Open Source
Opera
ORM
pagination
Pair Programming
papervision3d
Patterns
Peer Creation
Performance
Personas
PHP
plugin
preloader
process
Web/Tech
Progressive Enhancement
Project Website
Prototype
Prototyping
PV3D
QA
qooxdoo
Radiant CMS
rails
Really Simple History
References
Requirements
Requirements
Alice Toth
Requirements Visualization
Restlet
RETE
Review
Rich Interactions
ruby
Ruby on Rails
SaaS
Safari
San Francisco
Scalability
Scenarios
Scriptaculous
SDLC
Search
Security
Selenium
Semantic web
SEO
Server Side
Silverlight
SOA
Social Networking
Software Processes
Songbird
Sprajax
Spreadsheets
Standards
STI
Story Telling
Struts
Task Flows
Test Driven Development
Testing
Tilt Component
Tools
Training
Trends
Tumblr
Tutorial
Tutorials
Unit Tests
Usability
Usability Testing
User Experience
user experience design
user interface
User Interface Standards
User Research
UXD
Video
Visualization
VLC
Volta
Web/Tech
Web 2.0
Web Design
Web Development
Webkit
Weblogs
Web Services
Web Standards
Widgets
will_paginate
Windows
Wireframes
WordPress
workflow
XML
XML Metadata
XUL
Yahoo Map AS3 API
Zeigarnik
Zeigarnik Effect
ZK