Documenting Website Requirements and Design

10,000 Foot View
Over the years I have seen a lot of different ways to document software. For the most part the level of effort spent on documentation has been inefficient. It is easy to spend too much time on documentation. It is even easier to spend too little.

Ultimately there needs to be a measuring stick to determine what level of documentation is appropriate for the software being developed. Documentation can be in the form of code comments, requirements documents, and user manuals.

Code comments should always be used. Undocumented code is inefficient due to the level of analysis required for maintenance updates. Always comment your code! User manuals are not necessary for consumer facing web sites. If your site needs one than your user interface is ineffective.

So where is the line drawn for requirements and design? To answer this question I have a very simple measuring stick. If it is painful to not have something documented then document it, if it can be omitted and not cause pain then omit it. Keep in mind is the project you are working on and the team.

If software is developed in an iterative fashion then there are really two key categories to keep track of. The primary focus should be on the current iteration. Too much noise will only cause extra distraction and slow the team down. However, the future features should not be simply tossed aside. Instead they should be kept in a log or list of some sort. This list can be grouped into later iterations.

Documentation Specifics
Context goes a long ways to giving a framework everyone can operate from. For this reason it is important to understand why you are building software and what the overarching purpose of the solution is going to achieve.

This can be a business case document of some sort but it can also be as simple as a paragraph or two. This is really more like the mission of the software. There will likely be a lot of business details that someone will manage but for the sake of development this is less significant.

In order to get a sense of scope it is helpful to have a high level feature list. Features are broad and describe critical elements of the software. Be careful to keep the features simple and do not be too specific. A bulleted list of elements will suffice. The list can be something like: video player, partner video blinx widget, tools widget, featured articles, etc.

Features can be implemented in a given iteration or multiple iterations. It is likely the specifics of the feature will change over time as the actual details are fleshed out. Details of the features are documented as requirements. Of all the design oriented work products requirements are the most important. They act as a contract so business knows what to expect, so developers know what to build, and so QA knows what to test.

Other design assets can also be helpful. Scenarios or Use Cases help to give a user based view of the solution. I do not advocate detailed Use Cases because the level of effort required to complete them has never provided enough value relative to the amount of work. Instead, just give enough information so the team can understand what is happening for the user. They should depend on the requirements to flesh out the details.

Sequence Diagrams and Class Diagrams can also be very helpful. If a particular implementation is complicated a Sequence Diagram can add clarity. A picture is worth a thousand words is a key concept here. Remember the pain measuring stick; if you don’t need it don’t do it.

How to document
Using Word, Excel, Visio, etc can help and they are all good tools. The key challenge with these applications is that they are very manual. They don’t really make a model that can be worked with. In addition, UI Designers build mockups and Information Architects create wireframes and flow diagrams. Each work product is someone’s view into the software; each interpretation ads things that were not added before.

A development team (or system analyst) must assess all work products to make sure all requirements are included and there is one contract for the team to share. I have been using Enterprise Architect for a number of years now. It is a great UML tool although it has a lot of bells and whistles that I don’t use. I like to keep things simple. It is very easy to add requirements into the tool. It is easy to move them around. If is easy to group them by feature or some other structure.

Enterprise Architect View of RequirementsI create a requirements package and one for other types such as actors, use cases, etc. I then group the requirements by common/global and page specific. It is important to use a structure that works for the entire team. I use the global and page specific so that QA and business can understand the structure. It is very important to put a requirement in only one place. If a requirement is used in more than one location is should be a global requirement.

Initially I will re-create the requirements from all of the available work products. I add a TBD for all open issues. Then I re-order the requirements so they are ordered based on where they fall on the page or based on importance.

I then produce a Rich Text Document for the requirements based on the package. This can also be done for the other packages. I then import the RFT documents into a Word file that I’ve created. The Word file will have a cover page, TOC, and high level summary info. I then insert the RTF documents (can be done with a Macro).

Once the documents are inserted I open the Format > Styles and Formatting pane in Word. I’ve created a style for TBD which is several font sizes larger, bold, and underlined. I then search for all TBD text and change the style. This gives me a Word document with all TBD very easy to see.

I use this as a list rather than having to make another list to follow-up on. At the first meeting or two we address only the TBD’s because they are the risks. Once the big holes are plugged we will review the requirements to make sure that everyone understands them and has a chance to provide feedback.

Another valuable feature of Enterprise Architect is that I can create a RFT document that lists the requirements that have been updated since a certain date. This list can then be put into the appendix. Now it is very easy to see what has changed since the last update.

One final point to stress is that the project should be moving as the requirements are being fleshed out. Development environments should be setup, proof of concept or baseline architectures can be made, etc. The project should keep moving. At some point the requirements for a given iteration or phase should be agreed to. Then for that iteration those requirements will be frozen. However, they can be changed for a future iteration and the rest of the requirements can continue to be fleshed out. In the end there should be a contract that determines what is developed, tested, and expected by business.


1 comment so far

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

%d bloggers like this: