How To Create a Web App
This is the second post in our series on how to run a startup and develop a product. In part one, How To Bootstrap Your Startup, we outlined the process of bootstrapping your company into existence. In this post, we show you how to go from idea to specified product. By the end of it, you’ll know how to build a mock-up of your business idea and write the most important document you’ll write for the company: your functional specification.
For a simple system the process outlined in this post should take you a month. For a complex build, there will be a lot more research and your mock-up and functional specification will be big - so budget 3 months of full-time work.
A Word on Strategy
Every good business begins with a solid understanding of the proposition and business plan - in short, your strategy. It's worth reading Guy Kawasaki’s 10/20/30 Rule of Powerpoint; it’ll provide you with an idea of what should be included in your business plan and strategy. Your actual business plan should be in a lot more detail than Guy describes in his post – his rules relate only to how the results of your work should be presented, not how the content should be derived.
From Strategy to Development
Whether you are out-sourcing or developing in-house there are two ways to build a system:
- Give your developers a rough idea of what to build and keep iterating the design as they build it;
- Give your developers detailed documentation of what to build.
When out-sourcing, the second option is always cheaper, faster and lower risk. Not only that, but the end product will be better architected, more coherent and easier to maintain. Given this, it might surprise you to learn that the vast majority of out-sourced developments do option 1. Don’t do it - option 2 is more work at the start but entirely worth it. The basic premise of option 2 is simple: instead of relying on your developers to think through your business properly, you take responsibility yourself. You’ll do this in two ways - firstly by creating a mock-up and then by documenting that mock-up in a functional specification.
Your mock-up
The first thing you need to do is get yourself tooled up is to create your mock-up. This requires a visual web-editor (assuming you’re building a web-application). Personally I use Visual Web-Developer from Microsoft - it’s free and powerful. However, it is also very complicated to use, as it’s a full web-development environment. If you don’t know how to code in C# then it is probably easier and faster to use Dreamweaver, Frontpage or the freeware KompoZer.
A mock-up is a run through of your site and the learning process you’ll go through as you create it will be exceptionally revealing. It sounds simple, but when you start to put pen to paper you’ll very quickly find that it isn’t. Your mock-up is the first stage of building a real understanding of what your system has to do. The mock-up should contain no functionality and doesn’t need the final graphic design. Its objective is to help your developers understand what information the system should capture, when it should be displayed and what it should do when the user "does stuff" on your site.
To give you an idea of how it should look and feel, I’ve created a small mock-up of an email service for you to peruse. Granted it is a mock-up for a terrible email service, but it should serve the purpose of detailing what a mock-up should be. When you’re building the mock-up, remember to include an admin interface – believe it or not, it is easy to forget to include this. Make sure you think through how you will administer the system, handle customer queries, examine user accounts, run reports on user numbers and website traffic, etc.
Only when you’ve completed your mock-up and been through several iterations with any other business partners, are you ready to move onto the next stage - documenting it in a functional specification
The Functional Specification
This document is the most important document that you’ll write for your business. It will tell the developer exactly what your system should do. It will contain every page you’ve created in your mock-up; and for each screenshot it’ll explain what’s happening on the screen, what the user can do from there and what the system should be doing in the background. The document is called a "functional" specification because it should describe "what" your system does, rather than "how" it should be done.
The first thing you need to do is get tooled up. Write the document in Word (or an equivalent). You’ll need to include a lot of screenshots - for this I’ve always found the Firefox plug-in Pearl Crescent Page Saver invaluable, because it lets you take screenshots of a whole webpage (not just the part which is displayed). Secondly you need some software to create flow charts in. I used WizFlow before we bought Visio from Microsoft. Wizflow is easy to use and does most of the stuff you’ll need.
When you set out to write your functional spec, you need to follow a clear structure so that your developers understand what you are saying. The structure which I always use is:
- Confidentiality notice – make it clear that this document is your property and you are serious about controlling your IP
- Introduction – you should describe your company, the structure of the document and a one paragraph overview of your system
- User scenarios – Include at least 5 clearly written accounts of what a user might do on your system. These serve to ensure that everyone who ends up on the development team knows what the system is for. Write them as a chronological story.
- Overview of the system –five page description of what you system should do; keep it very high-level and include a system overview diagram (see below).
- End-user functionality – a section for each system module (see below) in the system overview. Each section should include several sub-sections for each possible action within that module.
- Administrator functionality –section for each admin module and sub-sections for each possible action.
- Non-functional requirements – design integration, SEO, availability and uptime requirements, scalability requirements and load calculation, data validators, security and back-up and the development platform (if you have one).
Clearly in a blog post I cannot cover each of these in detail, but one element which is particularly important is your system overview diagram. Whilst the developers might not build the system in this way, it is useful for you to mentally split your system up into modules. I’ve done a simple example using the email system used in the mock-up:
In the above simple example, the four boxes are the four major sections within the "End-user functionality" section of the functional specification. Within each section you should cover, with precision, what all of the possible actions are and what the system should do in each case. From this it is easy to build out your document structure. So for "user access" we’d need a sub-section on "Create account", "Log in", "Forgot password", etc.
Start by building out the document structure. Only when that is complete should you start filling out all the details. This way, you’ll slowly build up your document without feeling overwhelmed by it. When you are writing one section, you’ll get ideas for other sections – when this happens go to the relevant section and add the thought in square brackets so that you know what to cover when you get to it. Trust me on this: only one person can author a functional specification. More than one person can review it, but only one person can author.
A Word on AJAX
You seemingly can’t launch a new web site these days without using a few dollops of AJAX here and there. However, you can’t incorporate AJAX into your mock-up, as there’s no functionality. Where there is a functional requirement for AJAX, you’ll need to use a new page in your mock-up (the complete opposite of what AJAX gives you). Therefore you need to explicitly include your AJAX requirements in your functional spec. Personally I insert my AJAX requirements in a box, so they are clear to the developers.
Container Documents
In parallel to writing your functional spec, start the following container documents:
- Future ideas for the development of the system;
- Legal points you want to make sure that are included in the terms and conditions;
- Any design thoughts (include here screenshots of website designs you like);
- Patent ideas;
- Marketing ideas.
As you are working through your functional spec, you’ll come up with lots of ideas in all of these categories (and possible more). Make sure you’ve got simple lists you can just drop them into – get them out of your head and into the computer as fast as you can, so you maintain a clear mental space free from idea clutter.
Conclusion
Creating a quality functional specification is a time-consuming - but essential - job. Take your time and do a quality job. Don’t be surprised if the document ends up being hundreds of pages long. But it vastly increases your chance of delivery.
In the next post I’ll be looking at how to build a long-list of developers, run an RFI to create a developer short-list, run an RFQ to select a vendor and a spare, and then what to look out for in the development contract.
[Ed: Thanks Matt for continuing this insightful series. To see how Matt puts all his theory into practice, check out his own start-up Aroxo. You can sign up for their beta trial using the code "readwriteweb2".]
Share2 TrackBacks
TrackBack URL for this entry: http://www.readwriteweb.com/cgi-bin/mt/mt-tb.cgi/1673
Comments
Subscribe to comments for this post OR Subscribe to comments for all ReadWriteWeb posts
Matt, thank you for yet another great and very useful post. More of this and faster, please;).
Sorry Serkan - next one will be faster out of the door!
Interesting post, Matt. I'm currently going through the spec process right now, but from a very different angle. I code in XHTML/CSS, so I'm spec'ing the service and coding the finished front-end all at the same time. I'll soon be ready for developers to come on board, and they'll see a very clear vision for the product (it looks and functions very much like a finished app). It takes me less time to put everything into code than it would do to write it out and plan it in Visio, and it also means that I'm actually building part of the finished product, too. I can't recommend learning XHTML/CSS highly enough for budding web entrepreneurs.
I am not sure if I am misreading this - but are you suggesting that a top down, water fall process works better then an agile /iterative development approach? I can see that there is a case to be made for both scenarios, but I do not see you making any. I think your oversimplified advise "don't do it" for option 1: "Give your developers a rough idea of what to build and keep iterating the design as they build it;" is highly problematic.
Hey Alex - I'm arguing that when you are out-sourcing your development you should ensure that you have a very clear brief and documented set of requirements.
If you are sitting next to your developers and they are directly employed by you, then the situation is different.
Great stuff Matt, cheers for sharing this, appreciated. I'm about to start authoring an idea and I totally appreciate your comment: only 1 person can author it.
In all of my projects, that 1 person is always me and I often feel that I probably spend more time documenting and writing up the specs than the people I hire spend implementing the ideas ;-)
This seems like a great opportunity for me to plug a series of articles I wrote discussing the technical side of coding your first, basic web app in PHP:
http://paulstamatiou.com/2006/12/27/how-to-code-your-first-web-app-part-1/
http://paulstamatiou.com/2006/12/28/how-to-code-your-first-web-app-part-2/
http://paulstamatiou.com/2006/12/29/how-to-code-your-first-web-app-part-3/
Good post Matt. The only thing I would suggest is go into some detail about diagramming and illustrating requirements, such as suggesting diagram types (UML, Page flow, org charts) and perhaps diagramming tools (SmartDraw, Visio)
I find that this helps me express my vision in a way that developers can understand, and being a developer myself I can't begin to describe how much clearer a customer's requirements are when they're illustrated rather than spoken. There are innate vaguenesses in human languages which present challenges during the requirements phase of a project, but a lot of graphical languages like UML eliminate some of these clarity issues.
Another great post Matt!
Like some other commenters, I'm favor of "illustrating" requirements in addition to using text. Did you use wireframes at any stage of your mockups? Do you have any online tools to recommend for wireframes or mockups? It'll be really helpful if we could browse & import templates, and then tailor them to suit needs.
Hi Rachan,
We started on paper. Running through different ideas and concepts for how some of the key system stages should work. This enables to get us to a point where we were pretty confident in what the system should look like when we sat down to create the mock-up.
In practise, for Aroxo at least, our mock-up was almost like doing a RAD build, but without the functionality. Once we'd got a tight mock-up we'd won the battle.
M.
I notice that my site (www.aroxo.com) is currently down. There's an engineer currently looking at it, hopefully it (along with the email mock-up) should be back online within the hour.
As a Project Manager, working on different web projects outsourced to Ukraine I disagree with some parts of the approach mentioned here. My experience says that if the development team relies on mockups and documents created by customers then the team and the project are in a real trouble. Documents and mockups created by the customer are awful in all cases!
Why Matt doesn’t mention an option number 3? Create the right documentation TOGETHER with the development team. This is how we do it in our company with our clients who want to outsource with us. We create mockups, we create the right documentation. The documentation created by the client can be a starting point only. We ask questions and in most cases we’re trying to predict customer needs in the documentation to get started. The client always reviews the documentation and it’s much cheaper for him to make changes – to the documentation, not the code.
This part of work is paid separately. We create good documentation suitable for any development team. Then we estimate the development time and inform the client about our fixed price for the project within the scope specified in the documentation. The client can give the documentation to another team and run the project with them. Although this has never happened :-)
With this approach the client is very confident that he gets what he wants, gets our consulting, and gets good documentation and gets correct price for the project which is easy to predict (estimate time) because requirements are known. I know about cases when our customers managed to get investor’s money with the documentation.
Will you create full design for your future house on your own OR will you create a sketch and let the rest to be done by a professional architect?
Hey Vladimir - actually this is an entirely fair point, there's no reason why the developer cannot be paid to peform the work.
Thanks for your comment.
Great thoughts. I myself have worked for a few overseas projects (as a programmer) so I can relate to the need for better documentation and communication from the clients' side. Many projects fail because clients don't communicate the specs during the early stages.
This is a far too simplistic approach to developing a full software system. This will result ( most likely ) result in a bad designed system..
And the functional requirements or not the only requirements. Think about quality requirements..
You cannot learn how to build a webapp in a single article
fyi - your mockup has errors:
Warning: Unknown(e:\domains\a\aroxo.com\user\htdocs\email\): failed to open stream: Permission denied in Unknown on line 0
Warning: (null)(): Failed opening 'e:\domains\a\aroxo.com\user\htdocs\email\' for inclusion (include_path='.;c:\php4\pear') in Unknown on line 0
Great article.
I think, if you can swing it, the first round of the core technology / IP should be developed by the founders. Sometimes this means developing it in the evenings / on weekends and takes away from family time (if you have one) and marketing, etc. but you at least have it exactly as you wish. It's always a tradeoff.
Outsourcing can also be used effectively for the more mundane aspects of the project. I fully agree that everything must be well-documented up front. It's often too complicated to expect much of an agile dev model with people thousands of miles away. It works sometimes but you need a special team.
I know. There's a configuration problem with my server. The engineers are currently working on it. Very annoying as we just made the front page of digg. :(
Interesting post, and nice blog!!!
Good tip for app development:
Make sure that you separate the live version of your app from your testing version, or one you're adding new features to ("debuging!").
Ahem, aroxo.com! =)~
Hurry up and fix it so we can all see the app!
Rich
Hi, I run a business with a friend and we make custom web apps.
Please excuse my English as this is not my first language ;)
From my personal experience, it is best when before the start of the project you get together with the client and do as you suggest in option 2.
We get together with them and in 2 or 3 meetings compile a list as detailed as possible of the functionality and requirements of the project, this is what you would call the detailed documentation of what to build.
After a few weeks of working on the project we get together again and do a review and more work.
Then, in the last week or so we go and finish the project with someone working where the actual project is going to be implemented. Talking to the people who are going to use it and getting immediate feedback from the client.
This is what has worked for us in making a better application.
Good luck =)
I'm sorry, but your web site is not working. Therefore, you are fired.
I agree with the article. I am building a web app now. It is always better to build the mock-up of your service. You know what you want and how it should work. Build out everything in css/xhtml and use javascript to open and hide divs with dummy data (for Ajax simulation). Why do this? Because you'll be building it from a user's perspective which is? Right, the MOST IMPORTANT THING. It will change a lot, but by the time you have all the kinks worked out, all you have to do is use cases and you're ready to go.
Matt,
Awesome write up. I follow a very similar method for Clever Tools. As for mocking up, I use a great program called Axure. I worte an article about it at Rev 2 here: http://www.rev2.org/2007/09/25/axure-rp-prototype-your-startup-and-applications/. It seriously is great software for mocking up and prototyping your web app.
Another point: if you're going to write long detailed functional specs, make sure that you reduce time wasted trawling through unnecessary bits by hyperlinking relevant sections, and ensuring that any interaction design (AJAX-style animations etc) are fully diagrammed alongside the user stories.
But in general, threshing out a concept through evolving user stories has IMO got the job done faster and with less 'fence tossing'. If you're outsourcing and can't get the product owner on site, use Basecamp or Huddle etc for collaboration. It's better to evolve and collaborate than try to annotate every one of your thoughts in a single document and hope that you've thought of everything (which invariably you haven't).
andy
I did some research for prototyping tools and found a few free stencils for Visio - www.swipr.com, www.guuui.com, http://looksgoodworkswell.blogspot.com/2005/11/visio-wireframe-toolkit-for-download.html
Axure is another tool I found (expensive, also mentioned above by Jason); here's a review of Axure - http://www.guuui.com/issues/02_06.php
That's quite a simplified version of this setup to create a web apps. It may be helpful to provide an example or a tutorial - I'll definitely learn a lot from there.
Hi Matt,
I'm wondering what your thought is about building webapps on top of existing CMSs (Drupal, Joomla etc). Did you look into them or do they not apply to your business?
-Thanks
Here's a review I saw yesterday at WebWorkerDaily about a really slick prototyping tool/service for web app development.
http://webworkerdaily.com/2007/10/25/another-approach-to-free-collaborative-site-prototypes/#more-1251