How do I create a clear and professional document to outline my online application?

January 30, 2007 3:28 PM

I'm helping design a new online application at my work. I've managed and designed this type of thing several times, but have always worked with friends in an informal environment. For this project however, it needs to be completely legit and professional. Are there any formats/templates/standards I can or should use to list features, work-flows, data models, etc.?

For instance, if I was going to document the process of writing a new wiki site, or perhaps a blog engine, how would I go about listing features, how the data would be stored, how users would integrate with content etc. There may not be a default way to do this, but if anyone has any past documents that show how they presented the data, I would be stoked to see how it was organized.

thanks

posted by adrock31 to computers & internet (9 comments total)

There are a lot of great resources out there about this kind of work, some created by members of our very own MetaFilter.

Communicating Design: Developing Web Site Documentation for Design and Planning by Dan Brown has earned raves from a lot of people I truly respect in the IA world.

Jesse James Garrett's The Elements of User Experience is a few years old, but is still indispensable for me. Especially when paired with its online resources and the Visual Vocabulary, you've got an entire set of smart, coherent tools for documenting your work. (You might want to tack on his IA site as well.)

You might also want to take a look at the portfolios of firms or consultants you admire -- they often show off their deliverables to prospective clients as a way of distinguishing their work. Learning from those real-world examples can be invaluable.
posted by anildash at 3:47 PM on January 30, 2007 [1 favorite has favorites]

Anil's comment on JJG's book is spot on. Unfortunately the book doesn't really encompass the full breadth of things you apparently need to document - it focuses on functionality, layout and flow (and the visual vocabulary does as well).

I've encountered the problem of a lack of clear language that covers data organization, functionality and layout. Maybe something like that shouldn't even exist (as three areas are clearly distinct). There are, however, several "languages" or semi-standards you can (and probably should) use to document each set of things.

Specifically, you can use UML to document the data structure (your regular DB schema), application classes and how those work and relate. You can use JJG's visual vocabulary (which I would argue shares some similarities with UML) to document flow and how functionality behaves; And finally, you can use wireframes to document how the product should "look" at a higher level.

Each of those 3 standards allows you to document things at three different layers of the whole product. A document that describes why things are the way they are, and that uses these visual vocabularies to illustrate the points, is the way to go.

(And this is a great question, it made me roll up the sleeves and register a new MeFi account. My old one was lost somehow)
posted by fredoliveira at 6:12 PM on January 30, 2007

Diagrams. And bottlenecking.

You can never go wrong with charts of the most-common (predicted) activities vs. the processes and steps required to perform each. You want the highest-use facilities to be the ones that get the most attention and that perform best.

You'd be surprised (or maybe not) how many systems I've seen where the most-common activity is the least-efficient.
posted by rokusan at 8:16 PM on January 30, 2007

Check out these Microsoft Word templates. They are based on the RUP (Rational Unified Process) artifact set.
posted by jknecht at 6:23 AM on January 31, 2007

UML (Unified Modeling Languauge) was made to express just the sorts of things you need to express. You can use it to model features, workflows and data to your heart's content. Contextual Design: A Customer-Centered Approach to Systems Designs provides a nice introduction to some basic UML models, and it also teaches you a lot about user-centered design in the process (I used the book for a systems analysis class and found it much easier to parse than the dense chapters we read from books written specifically to teach UML).

Also, as much as I hate to admit it, Microsoft Visio is a nice tool for making all the UML models you'll learn about.
posted by that_one_guy at 8:56 AM on January 31, 2007

Wow, great resources mefites, thanks a lot. All of those suggestions continue to help me gather the languages and structures of what I'm trying to accomplish, so thanks.

One further question, I'm having trouble finding a polished, finished example of some of this stuff. I'm not much of a designer, and while I can write up docs and create an Omnigraffle chart, I'd love to see how people bring it all together in a way that is nicely presented, and consistent with the company's identity. I'm not sure if there are open book versions out there, and as Anil suggested, some companies publish theirs after the fact, but I haven't been able to find any. Any suggestions? Seeing a real-life example would also help it sink in, as well as make sure I don't miss anything. But thanks so much for the resources so far...
posted by adrock31 at 9:01 AM on January 31, 2007

Boxes and Arrows has tons of articles on documentation, and some of them include templates.

Information architecture templates for OmniGraffle and Visio. More Visio templates.

Webmonkey's Information Architecture Tutorial is pretty good.
posted by kirkaracha at 9:32 AM on January 31, 2007

IA Stencils for OmniGraffle

Creating prototypes with OmniGraffle
posted by kirkaracha at 9:34 AM on January 31, 2007

Also OmniGraffle web design template and wireframe palette, and Graffletopia has tons of stencils.
posted by kirkaracha at 9:43 AM on January 31, 2007