I weep when I think back to how much time a project home page would have saved me in photocopying, proofreading, and distributing documentation. When I took the reins for a network library development project (NetFunc) a few months ago I vowed "This time it will be different."
One of the most useful tools I've come across in recent months has been Steve McConnell's Software Project Survival Guide (Microsoft Press, 1998). We'll take a closer look at one of McConnell's recommendations - the project home page. Though this article is primarily aimed at project managers in charge of tool or library development, the process will work well work for game teams and subteams (design, art, asset management, programming, audio, and so on). I'm making two assumptions: you have documentation for your product, and you can post materials to your company's intranet with relative ease.
A project home page lets you and your managers keep your fingers on the pulse of your project. The project I'm involved in is developing a component for our company's multiplayer game titles. We need to make sure that our product works with four games that are also under concurrent development. That means dozens of possible requests for status and documentation. The purpose of your project home page is to show others that your team is (hopefully) doing what you said it would be doing, and to demonstrate that you're not afraid to let people know where you are in your development process. You should include screenshots and other materials only if they are part of your design documentation or if you're using the home page to make sample assets available to others. Otherwise, simply create a project logo in PaintShop Pro and be done with it.
Paradoxically, the more documentation you post, the less actual paperwork you'll have to deal with. Colleagues need a status report? Upper management needs a copy of the latest design document? Marketing weasels need a list of selling points? Send them a link to your project home page. In a large company, the project home page may also give your team an identity. This is especially true where membership on internal development teams doesn't have the cachet of membership on game teams.
Of course, it's not enough to create the documentation, post it to the project home page, and forget about it. You must maintain it. But with this system, you need spend no more than a few hours a week. OK, maybe the benefits of easy access to project status and documentation and visibility don't quite do it for you. Maybe it's just me, but I like being able to answer nearly any question about my project from any machine on the company network. Wouldn't you? And think how much easier having an up to date home page will make your project wrap-up, asset package, and postmortem period.
You may be thinking, "I don't have time to design a project home page." Neither do I. That's why I used McConnell's template, then adjusted it according to the needs of my project. Your project home page is different from your product’s external home page (the one Joe Modem can see). The audience for your project home page is management, your colleagues, and most importantly, your team. Thus, you can skip excessive screenshots, fancy backgrounds, cool animations, sound, and so on. Present "just the facts, ma'am."
A template for the project home page described in McConnell's book is thoughtfully provided for all takers on the Construx company web site. You don't even have to buy the book to get it. However, you’re doing yourself a major disservice if you don’t also purchase and read the book. Remember that if you use McConnell's templates, you’ll need to include (or not remove) the Construx copyright information from the HTML and document templates. You can see some samples of my project home page 1, and project home page 2 as well as the project task list. You can see how the page changes over time as documents crucial to the early phase of the project (for example, the Requirements page) were archived and new documents added. Our project page contains current versions of:
- Project vision statement
- The Business Case for the project
- Current schedule estimates
- A list of team member names
- A list of project customers
- A project contact name
- An MS-Project file for the project
- Software Development Plan
- Quality Assurance Plan
- Risk Management Plan
- Change Control Plan
- Software Development Plan
- Requirements Specification
- Requirements Summary
- Top 10 Risks List
- Copies of Project Managers (i.e. my) status reports to management
- User Interface Style Guide
- UI Prototype
- User Manual
- Q/A Checklist
- Proposed Enhancements and References.
As an aid to people less familiar with the details of your work, you may wish to split out and post executive summaries of your longer project documents.
What do you do with the old versions of your documents? If you’re running Source Safe or a similar version control tool for your project, Source Safe can archive old versions automatically. If you don't know how to use Source Safe, bribe a programmer to teach you the basics and use it to keep version control of your documentation (another gem I learned from McConnell).
The Rest of the Story
OK, Rick, I'll create a project home page. What else do I need to know? Here are a few more kitchen-tested tips:
1. Update the documents every few days. Make it easy on yourself and do no more than a few documents per day, though you should try to update schedule information every two days.
2. If a project page document is no longer updated on a regular basis, just keep the latest version on the page and mark it "Inactive."
3. Put the bad news (such as schedule slips) on the schedule as well.
4. Include a shortcut to the project home page on all internal e-mails about the project.
5. Be careful about putting memos verbatim on the home page, especially where candor may work against you (such as discussions regarding the performance of another employee or team).
6. Let people know which nonstandard application they’ll need to read the document. A UI prototype created in PowerPoint, for example, should say "Requires MS-PowerPoint."
7. Date each of the links with the date of the version of the underlying document. This system lets people know how current the information is and helps you keep track of what needs to be updated.
8. You don't have to convert the documents to HTML if you’re using other applications to create them. Simply copy the files into a folder labeled "docs" on the web. When users click on the link with their browser, the selected document will automatically load in the appropriate application.
9. Split the web directories in any way that makes sense to you. I’ve divided them into docs, code, and graphics.
One interesting feature of McConnell's project home page template is the anonymous feedback form (ask your intranet guru how to set this up if you don't know). Anyone in the company (including your team members) can tell you what they think of the project without fear of retribution. Oddly, no one has used this feature yet on our project home page. I've kept it anyway, just in case.
For a one- or two-person shop, a project home page may be overkill. But in any environment where you have to gather the intellectual resources of several people and explain them to perhaps dozens more, a current project home page is critical. With enough preparation and commitment, you can create a clearinghouse that not only lets you gather all relevant project documents, but also helps generate visibility and accountability for you, your project, and your team. In fact, if your page is well laid, out your colleagues (and your boss) may even think you’re well organized.
Best of all, creating the documents that you need for the project home page compels you and your team to get important issues out in the open — and recorded. The project home page was an essential component of the on-time and relatively low-chaos delivery of my network library project.
Still, you may not want to go all-out and create the entire dozen-plus documents that McConnell (and I) recommend you create. Keeping at least your basic product design, technical design, and requirements documents on the project home page will go a long way to helping you and your team make it through the development process.