We've been having discussion in our department regarding workflow, communication, and automation. There came a point in these discussions where I described a system that I thought would make things simpler for us as a group with an interface that we and new hires alike would find useful.
I thought I was describing it eloquently. But then again, I knew what I was describing.
But there are other practical obstacles to communicating such ideas. For example, your team may feel they have better things to think about. Maybe they are biased towards their own ideas, or that this is a waste of time because dammit the current system works fine if only you weren't whining so much, or whatever their mind has wandered off to at that point of the meeting.
In the end the boss decided to steer the meeting by relenting to a "write something up and work with <coworker> on this, we'll discuss it after that" approach.
I should back up a little bit here...I'd grumbled about a lack of documentation on the state of the in-house project growing in our department for awhile, but because grumbling isn't seen as productive, I felt the concerns were dismissed. What I later understood was it wasn't a lack of documentation so much as a lack of a functional specification. Others on the team didn't understand the problem until we were in a meeting and three people had three totally different ideas on how the system did something. Because the application was in a functional state, there wasn't a problem seen. It was doing things, right? No alarm bells, nothing broken...move fast and break things then fix them later. Whiners were just falling behind.
Observation One: Functional specs aren't necessary to have a "working" system, but they can keep people on the same page.
Maybe that works until it dawns on everyone that what they know is wrong.
"But you're not describing a functional spec," you might say. "How a system does things is a technical spec!"
That's true, but sometimes the how something works affects the user interface and interaction...in this case there are ways of doing things that the system may mysteriously change behind your back without notice. That's an interface interaction that ideally is covered in both a technical and functional spec. The proper workflow should be baked into the functional spec.
The immediate reaction...thinking this is a documentation issue...was to have people document how the system worked. Which isn't bad to have for reference. But it's a band-aid; a reaction rather than pro action. Reading it didn't give me a sense of what the end product was going to do or how it would fully address the future integration of automation...it was a snapshot of what had already been done.
In a way, it was kind of a postmortem.
Observation Two: Documentation is a blanket term with many sub-categories. Sometimes you have to identify what kind of documentation is missing before identifying that as a problem.
I spent some time reading up on functional specs and pondering how I would approach the problem. Turned out I knew someone who had written some nice introductory material on functional specs freely available on the Internet.
At its heart a functional spec is a description of how an application is expected to work with the users. It describes, in detail, how the application works with the user.
I then started writing. You would think this is easy. You would be wrong. Maybe if you have a really clear idea of every bit of the proposed application in your head coupled with experience in writing specs, you'll find the task easy. Chances are you'll find that clear idea of how you want to interact with and configure the system is just a set of highlights you expect in a working system. You don't realize the number of things you just don't think about or take for granted in a system that a decent spec calls for you to spell out. ("Oh...yeah...logout button? Or a logout link? Is it in a menu?")
Observation Three: The Functional Spec was longer than I thought it would be.
This was a relatively simple web application, or so I thought. Then I started describing the pages I had in mind.
One thing led to another which led to another. It didn't take long for the first draft to hit 15 pages.
Observation Four: Mockups make specs come to life, and bring out glaring errors.
I thought the mockup was best for presentation purposes. The spec tutorials heavily rely on humor for keeping people engaged enough to slog through the details of what I think a website should look like. As you can guess, I'm not really entertaining enough to keep my team reading my proposal.
A mockup, however, is a picture worth thousands of words. After I completed my first draft of a spec, I pulled out a copy of a mockup application called Balsamiq. I had never used it before and dreaded the learning curve; fortunately, the fears were largely over nothing. It wasn't long before I had the initial pages staged.
I also discovered several places where my descriptions, so clear and useable in my head, were simply impractical or felt wrong once they were applied on the mockup. In other places I discovered redundancies in function that overcomplicated the workflow. Trying to map this in my head from words on the page didn't quite work; the pictures illustrated what turned out to be glaring errors, and when I went back to the page on the spec, the errors on the written page were such that I could not unsee them. Doh!
Other times I discovered ways of doing things better on the mockup that didn't occur to me on the written spec. More notes were scribbled down for future reference.
Observation Five: A good mockup program can make a good presentation tool.
Mockups are new territory for me. I never had a job where spending time on a mockup of an application would be potentially useful. It turns out that Balsamiq is more than Powerpoint for interfaces.
I discovered that this program allows for linking pages together, a natural display of features for mocking up a web application. I can also export the pages to PDF and it looks like those PDFs will be interlinked as I set up the mockup project. Balsamiq also allows for the use of comment notes that can be hidden, describing features and workflow within the mockup itself. If my functional spec weren't so wordy, and if there weren't some features and description that aren't really illustrated in the mockup, I'd be tempted to just dump the functional spec text into a series of comments in the mockup and forego the use of the separate functional spec altogether.
Observation Six: The mockup has given me more notes for the rewrite of the spec.
Aw, dammit...more writing.
The first draft of the spec was a page-by-page description of the web application. After seeing the pages illustrated, I now have many notes scribbled on post-its and in the margins of a printed copy of the spec. Now I have to go back and re-write parts of the spec.
The first draft isn't horrible, if I do say so myself. But it if I am to present this to the team, it needs to have I's dotted and T's crossed, and it needs to be in line with the mockup.
There will no doubt be mistakes. That's no excuse to not try fixing errors.
Observation Seven: Order of dependencies matter, as does the ability to reference information in the spec.
This is something I learned about in a Ruby talk about communicating with developers. It's meant to be a good practice for giving presentations, but I think it also makes sense in certain types of writing.
In a technical description, you should not have a dependency on something later.
That is to say, if you're talking about something technical, you should avoid whenever possible a situation where you describe something but "if you don't understand X, it's okay, we'll get to that in a bit." I'm sure you've run into that before; I know I've heard it. In the talk, the presenter said that he's given his thesis statement, the most important bit of information, as a "header" to the discussion. If the attendee fell asleep at some point in the talk, he would already know the idea that the presenter thought was most important, and in the process of the talk there were little to no loose ends.
As I go back through the spec I'm going to try keeping an eye on my descriptions to see if they need to be rearranged a bit for clarity. I'll bake in descriptions when necessary and minimize references to other spots in the spec; that way if I eliminate sections or change how something on a page works it won't make another spot reference a non-existing bit of information.
I'm also going to try making the spec referenced with a table of contents, so pages and sections can be quickly searched even if printed. A spec is a living document. If you can't easily navigate it as it grows, it won't be useful.
Observation Eight: Specs and mockups can become a skeleton of a user manual.
The more I wrote and the more I illustrated, the more I saw the beginnings of a user manual for an application take shape. It makes sense...if a functional spec outlines how a user is supposed to interact with your application, and it describes the expected behavior of the application, well...that's the basics of user documentation.
This documentation...proto-user-manual...not only takes care of the initial design work that goes into the application, but also takes care of the initial steps for the dreaded technical writing involved in documenting how things work! Two birds, one stone! As long as it's kept up to date, that is.
I harbor no illusion that this work will not be for naught. This is a proposal for something that may never see the light of day. And while specs are not fun for most people, I'm finding that the work that goes into the initial stages of planning the application can be rewarding. It's quite a mental exercise to map out an application in your head, try to communicate that to the written word, translate the written word into a mockup, and then refine the written word again.
Even the tutorial for specs pointed out how often this step...the functional spec...is skipped. People like to jump right into coding in some kind of shoot-from-the-hip coding style and fix issues as they crop up. But after trying my hand at my first attempt at a spec, I wonder if spec writing and review is akin to the lack of respect for editors in print news; the industry knows they can cut editors and still have a product to churn out, and they justify it by citing the speed of their competitor, the "Internet," with which they're competing.
They completely ignore the number of glaring errors and botched headlines that slip through. And poor quality writing. The difference between a good editor's refinement of a news story and the shoveled crap that makes its way to print is the difference between a showman's presentation like Steve Jobs' Apple events and those painful talks where every third syllable on stage is an "um."
Another point; how much time is lost having to re-code for errors or changes that would have been caught had it been properly spec'd in the first place?
But those are speculation and opinion. I still have work to do...several more pages to be mocked up and then the second draft to work on. The hard part is squirreling away the blocks of time to work on them. The surprising part is that I'm actually enjoying the process!
Posted with Blogsy
No comments:
Post a Comment