Best practices or tools for defining specifications for a new website?

May 31, 2013 4:35 PM

My small team is hiring a developer and a designer to build a website. What is the best way for us to communicate the features that the website needs to have? It is a medium-complexity website - more than a blog, less than Facebook.

I'm working with a small team to build a website from scratch. It is of medium complexity and includes some social networking-style features: profiles, search, connections between users, newsfeed, etc. We will probably be hiring a developer and a designer to make our plans a reality.

What is the best way for us to list out the website's features? I am craving something that has an easy-to-understand format for giving detailed specifications to the developers.

It needs to describe the complexity of each feature, and the way that each page interacts with the other pages. (And, possibly, the data that it is pulling from the database to populate a given page.)

Is there a good tool out there for this? (Or a combination of tools?) If you've done this before, what have you used? I started by listing some features in a super-basic Word list, but it has quickly become too complex and all of the information is getting lost in there.

Thanks in advance for your advice!

posted by inatizzy to Computers & Internet (13 answers total)

You could use doku wiki.
posted by seemoreglass at 4:45 PM on May 31, 2013

Are you familiar with wire framing tools? That is one of the common approaches to defining a website's structure, layout, etc.
posted by Dansaman at 4:48 PM on May 31, 2013

You could also use a project management app like BaseCamp or Trello.
posted by Dansaman at 4:52 PM on May 31, 2013

Response by poster: Thanks guys. I promise not to turn this into chatfilter, but I think maybe it would help if I clarify that I'm comfortable with wireframes and explaining a layout -- but, I'm stuck on how to list out the specifications of complex features.

For example, if I have a page with a bunch of form fields (say, collecting basic profile information) -- some of them are required, others are optional; some can be made private, others are always public; some will be data that will be used on other parts of the site, etc. When I try to just write all of that out, it feels like a *lot* and like it's not something I could reasonably hand over to a developer. It's not very systematic. A wireframe doesn't seem like the tool to get into that level of detail, though I may very well be wrong and welcome disagreement. :)

So... yeah. I hope that helps better explain the issue I'm dealing with! Thanks again :)
posted by inatizzy at 5:03 PM on May 31, 2013

I'm comfortable with wireframes and explaining a layout -- but, I'm stuck on how to list out the specifications of complex features.

I often create/use annotated wireframes. Wireframe in top half of page, bottom half for numbered specifications (numbers corresponding to number icons adjacent or pointing to wireframe elements) and other detail. This is pretty standard practice at all of the digital shops I've worked.

Or are you afraid you won't have enough space to list all pertinent bits of info? In that case you should pair the wireframes with a flow diagram/map. Same basic idea but instead of page-specific wireframes you have rough visuals of the page with the entire flow mapped out and described on sequential pages.

And, sometimes, you're right: for really complex stuff you just end up writing a lot of words and drawing a lot of pictures. That's just sort of the norm.
posted by hapax_legomenon at 5:14 PM on May 31, 2013 [3 favorites]

When I try to just write all of that out, it feels like a *lot* and like it's not something I could reasonably hand over to a developer.

That's because it *is* a lot. Even a site with a slight amount of interactivity gets incredibly complex because of all the paths a user can take, error states, etc.

Annotated wireframes are good, but the bottom line is you'll have to communicate with the developer as you go if you want a good result. This is because, no matter how carefully you document, there will be edge cases you didn't think of. This happens with 100% of projects, whether it's two people working on it or 200. If you try to just "throw a document over the wall" and don;t communicate with the developer as he works, you'll probably be in for an unpleasant surprise when you try to use the end product.
posted by drjimmy11 at 5:23 PM on May 31, 2013 [2 favorites]

It sounds like you might be talking about documentation - here's an example I got by googling: web app documentation template.

Projects vary wildly, but this might give an idea of how to organize things and what types of info might be included. Ideally this would be something that you create as a collaboration with your developer, because they will have lots of suggestions for best practices.
posted by ella wren at 5:24 PM on May 31, 2013 [1 favorite]

. It is of medium complexity and includes some social networking-style features: profiles, search, connections between users, newsfeed, etc.

And incidentally, given that feature list, I would call that level of complexity to "high" or "very high." Don't underestimate how many possible paths there will be for the user to take when you get into essentially rebuilding facebook.
posted by drjimmy11 at 5:25 PM on May 31, 2013 [4 favorites]

Some options to look at:

Balsamiq, AxureRP, OmniGraffle. Also, Keynote (Apple's presentation tool).

Some are focused mostly on quick wireframing and basic mockups. Axure goes further into interactive prototyping, detailed documentation and collaboration. I don't think it starts to get into the task management aspects of collaboration, like BaseCamp or Trello do.

It sounds though like you need more than software tools, you need some grounding in software development methodology. That is, honestly, a big can or worms, because the people who care most about it can often be so far deep into it that they fight over nuances while forgetting the things they agree on.

Some high level and very incomplete perspective:

• You know less at the beginning of the project than you will at any other point in the project (but your perception will probably be exactly the opposite)
• Because of the above, you should avoid spending much time worrying about things that are very far in the future
• The most important question about a given functionality or feature isn't whether or not it is important, it is when it is important. This goes hand in hand with the prior point.
• What you think doesn't matter nearly as much as what your users think, so, make sure you figure out who your users are, and then engage with them early and often.
• Software needs to solve a users problem, not create new problems, so one of the things to understand about your users is the problem they want to solve, how they think about the problem, and what they consider "solved" to be.
• Everyone working on the project should know what they need to know when they need to know it, which is easier said than done.
• Communication is good, but too much communication is a distraction, especially for developers and others like them. So, establish a regular time for short checkins. Once a day is probably fine. Schedule it adjacent to another interruption, like the start of the day, before or right after lunch, or at the end of the day.
• If a developer has a question for someone else on the team, it is best if they can get an answer quickly.
• It is often faster to ask a question than it is to dig it out of documentation or email
• It is often faster to answer a question than it is to anticipate and document all possible questions.
• Creating a shared understanding among members of the team by communicating a clear understanding of the target users, their context, their needs, and other constraints on the project can head off a lot of questions
• Good documentation takes a lot of work to create, and even more work to keep up to date, so don't spend too much time on it. Often documentation artifacts are best regarded as opportunities and focal-points for discussion, rather than as ends in and of themselves.
• The world is changing, your knowledge is advancing, your plans should be changing too. So, try to deliver value early and often, and to take stock of and adjust course about as often. Once every week or two is probably a good guideline
• Knowing that something you thought would work doesn't work is business value
• Some of these things may be at tension with one another.
• There are no magic bullets. No methodology, process or tool removes the requirement that people to roll up their sleeves and work together to understand and solve difficult problems, at best they create a common understanding of how to do that.

posted by Good Brain at 5:35 PM on May 31, 2013 [12 favorites]

Annotated wires! I don't even know what to do with unannotated wires unless it's look at them and wish they were annotated.

Other than that, you can write a functional spec/user stories, and rather than go through explaining it, I'm just going to link you to this blog post and tell you to steal that guy's excel document, and modify it to fit your needs. I DO love the way he has it laid out, and it's just . .easy. THEN your developers can translate the use cases/user stories into actual work pretty easily.
posted by Medieval Maven at 7:18 PM on May 31, 2013

There's a product called Case Complete (on a phone, so this won't link: casecomplete.com) that promises to help you easily record use cases and requirements. I haven't tried it yet, but I'm an information architect who has to do every day what you're doing now, and I want to try it.

Failing that, you can either annotate wireframes directly in the wireframes doc, or you can number everything in each wireframe (be sure to also give each wireframe a unique ID), and make a companion doc that explains every numbered feature. We'll call this doc a specification or spec.

For the spec, your "explanations" as I've called them above can be chatty narrative--just notes, essentially. This works ok if the developer is using something he wont have to customize much, like an out of the box Wordpress theme. But what you're building sounds more complex than that.

The other option is that you already know how the content management system works (eg, Drupal, Sitecore), and your spec doc not only explains how every feature behaves on the front end but also what CMS feature (OOTB or custom) is to be invoked to make it work. This is called a content type definition.

Before you decide how to proceed, you need to talk to the developer to understand what level of documentation they need to build.
posted by ImproviseOrDie at 4:01 AM on June 1, 2013 [1 favorite]

Define requirements rather than specifications. Do so by writing "Use Cases". Manage those use cases with a system that does that. (I'll refrain from recommending one here because they all have pros and cons and I'd need to know more about your situation).

Karl Wiegers has written a lot on the subject and has quite a few articles for free online
Avoid these 10 Requirements Traps to Avoid
posted by at at 7:13 AM on June 1, 2013

The best tool for designing a website's specifications to give to a developer is the developer themselves. Everything else are just marginal improvements. An over specified project done without a developer's input is the kind of thing that seasoned developers know to avoid from painful experience.
posted by srboisvert at 12:34 PM on June 1, 2013 [1 favorite]