11.3. Different Areas for the Project Web Site This section contains some of the information that I've found useful on the project web pages that I have created. There is very little about web page design in this section; basically, the web pages should be as clear as possible, with as few clicks as necessary to get from any page to any other page. For medium-sized projects, most of the key information for each area should be able to fit on a single web page. The web pages should also work on every browser used by anyone in the project, including text-based browsers such as Lynx running over slow connections. Much of the information can be described using simple HTML, which makes retrieving it faster than having to open PDF or Word files. Many automated tools that generate reports already generate HTML. If not, then tools exist to convert the report to a format more suitable for browsing. 11.3.1. Home Page The home page is the default page for the web server. It should have links (often in a menu on the lefthand side) to the main page for each of the other areas. Other useful information for the home page could include: Messages about server outages and other current project-related news. When news items become old, move them to a separate location; don't delete them. A link to FAQs. The current status of various important builds. A search box for different parts of the web site.
Adding some RSS newsfeeds can also encourage people to revisit the page throughout the day. The feeds can even be project-related ones. 11.3.2. Getting Started One use of a project's web site is to help people to get started with the project. One document is the "I'm New Here" document. Other documents can be the "New Developer," "New Tester," "New Writer," and "New Toolsmith" documents. In theory, you should be able to give a new member of the project the URL of the home page and leave her alone for a few hours. Good information for the "I'm New Here" document includes: Names, email addresses, and locations of IT people and toolsmiths A step-by-step guide to setting up an account on a machine and accessing email Names of important servers, what accounts or permissions to ask for, and a basic overview of the local network Which directories and files are backed up, and when How to find a list of contacts for each project A link to a map of where people are located, with their time zones if the project is global
Once the new project member has a working environment, she can use the "New X" documents for information that is more specific about what she will be doing. An important part of these documents is a step-by-step guide to the basics of the job. For developers, this would be how to check out source code, how to build the product, and how to run it. For testers, the document would include where to get internal releases, how to install them, and how to run the automated tests. This is a good time to ask people to write down what they didn't understand or felt was missing from these documents. Every question you answer in these "Getting Started" documents is a question that you or someone else won't have to answer later many times. (Actually, what you'll have to say many times is, "Let me show you where that question is answered," but that beats having to explain something or other that you've just forgotten the details of because you haven't done it yourself for three or four months.) 11.3.3. Specifications The specifications web page is similar to any library, helping you to both find and read different kinds of documents. Grouping the documents into functional and implementation specifications and providing a place for developers' written notes about each feature in the product can help other readers later. A clear separation between speculative specifications and ones that describe what actually exists in the product is also helpful. One very useful document that can be automatically generated is a list of the available documents sorted by when they where first created and when they were last modified. Most documents that are wanted by people are recently written or recently updated documents. A good search tool is particularly important for this part of the web site. Section 11.4.3, later in this chapter, discusses this in more detail. The formats allowed for specification documents should be indexable by search engines and should be convenient for all members of the project to read and modify. PDF files are great for printing, but unless you have the right tools to modify them, people will have to create other files for comments on them. Plain text, Word, and HTML are some file formats commonly used for project specifications. Chapter 8 has more details about these and other file formats for documentation. 11.3.4. SCM Useful information about the local SCM environment includes:
Files -
Graphical browsing of the hierarchy of files managed by the SCM tool. You should be able to locate any single file and inspect and compare different versions of the file. It is also very convenient to be able to search for text in both past and present versions of files, and to be able to restrict the view of files to a particular branch. Tools that do this include ViewCVS (written in Python), CVSWeb (older, in Perl), Bonsai (Perl), and FishEye (a Java servlet). Some commercial SCM tools such as BitKeeper and Perforce have their own UI for browsing directories.
Change logs -
Change logs for the mainline and other branches, also arranged by project, showing the names, versions, commit messages, and usernames, grouped and sorted by time. Tools that do this include cvs2cl for CVS and FishEye.
Branches -
A list of major branches, their names, purpose, and creation dates. If a branch is unavailable for commits, then a message about who to contact to change this is a good idea.
SCM tool -
More information about the SCM tool, including details about how to configure it for each project. Providing some contact names or an scm-admin email alias for further questions about the tool is very useful.
11.3.5. Building Information about builds for the projects includes:
Current state -
If automated builds are running, a web page is a great place to display the results, especially if there are many different platforms and products being built continuously. The reports should include links to build logs and change logs. If there were any warnings or errors generated by a build, then another useful idea is links to the files and line numbers that generated them. LXR (http://lxr.sourceforge.net) is an open source tool that can create versions of source files that can be browsed, complete with cross-references to each file. Another useful page is a description of all failures of automated builds that were intended for other people, including the root cause of the failures. Documenting this is painstaking work, but it pays off when people begin to mutter that "there seem to have been lots of broken builds recently." The information on this page can show whether they are really right, or this is just a vague impression.
"How Not to Break the Build" -
A document describing the minimal process to follow when committing changes to the source code. When a build does break, check whether the root cause was a failure to follow this document; if not, add sufficient details to the document to stop whatever the actual cause was from happening again.
"How to Fix the Build" -
The counterpart of "How Not to Break the Build," this document describes where to find information about when the build broke, which files or tools changed since the build last succeeded, and who made those changes. This document should also describe how to rerun the unit tests.
Supported environments -
A single, authoritative place for project members to find out which machines, operating systems, and tools, and their versions, are supported for the project. Reports of other unsupported versions that have been found to work, or not work, can also go here.
Build tool -
More information about the build tool and the specific details about how it is used in various projects goes here. Providing some contact names or a build-admin email alias for further questions about the tool is very useful.
Historical information -
Tracking the size of the product and how long builds take can be useful information for finding out what's making the product so large, or why builds take so long now.
11.3.6. Testing Useful information for testers and other people includes:
Current state -
The latest results of running the system tests on different releases, including releases internal to the project and releases for customers. Test reports should include links to the definition of each test.
"How to Fix a Test" -
This document describes the processes for confirming that a test is failing and for escalating the problem appropriately.
Test tools -
A description of the tools used for testing, along with more information about using and modifying the tools. Providing some contact names for further questions about each different tool is helpful.
11.3.7. Bug Tracking Almost all bug tracking systems now have interfaces that can be used through a web browser. This allows you to refer to the following information from your project web site:
Bugs -
Access to the bug tracking system. To help infrequent users, include a way to get a reminder of the username and password.
Common reports -
Links to common reports for developers, testers, writers, and managers.
Submitting a bug -
Some guidelines for how to submit a bug for each project. A useful document here would include a summary of each area of the product and guidelines for choosing an area for a new bug.
Bug tracking system -
More information about the bug tracking system and how it is configured locally for your projects. Providing some contact names or a bug-admin email alias for further questions about the tool is useful.
11.3.8. Documentation Useful information about a project's documentation environment includes:
Documents -
Links to both released and latest versions of the product documentation. The release process should automatically update the links to the latest versions.
Review process -
A description of how the project usually reviews documents and provides feedback.
Building the documentation -
The tools required and the process to create the documentation as it is distributed to reviewers and customers.
Documentation tools -
More information about the documentation tools themselves. Contacts within the project for each tool are also useful here.
11.3.9. Releases Information about releases can include:
Releases -
Instructions for finding and downloading internal and external releases, often using their build labels (see Section 3.5). The release process should automatically update this page as releases appear and are approved.
Creating a release -
A step-by-step description of the process of creating a release. This is a good place for further details about what each step does in the automated parts of the release process.
Roadmap -
A link to a description of the features planned for each future release. This could also appear in the specifications web page.
Release tools -
More information about the release tools themselves. Names to contact for each tool are also useful here, as is a rel-admin email alias.
11.3.10. Maintenance Useful information about maintaining a product includes:
Design -
A description of the architecture of the product, ideally including both the original design and subsequent modifications.
Implementation -
Notes about the intentions of various developers who have worked on each part of the product. Previous maintainers may have kept notes about their understanding of each part, too. A good description of the directory hierarchy for the source code and the intended use of each directory.
Coding standards -
Coding standards for the project, to be followed by future maintainers.
Deprecation -
A document describing how to deprecate parts of a product's public API.
11.3.11. Support The support group will want information such as:
Support tools -
Links to the main tools used for tracking customer issues, such as ticket systems, knowledge bases, and other informative articles. Also links to tools developed by support for their own use when diagnosing customer problems.
Customer information -
A document describing what information to gather from a customer with a problem and, more importantly, why the information is useful and to whom.
Privacy -
A document about the privacy guidelines for customer information and data.
Triage -
A description of the basic steps for investigating a problem with the product. For example, how to debug a core file from a crash of the product and how to copy logfiles and core files to developers and testers.
11.3.12. Project Management Useful information about the people involved in a project includes:
Projects -
A list of all the projects, past and present, and email aliases for contacting the members of that project. A list of the names of the products for each project, including internal project names and older names, is also a good starting point for understanding what is going on.
People -
The people in each project and contact information for them. Charts showing the structure of different groups and people's roles in each project can help guide others when trying to decide whom to contact. If the group is part of a company, then a map of the offices (i.e., a floor plan labeled with who sits where) is great. Of course, someone has to update the map when people change where they are working.
Resources -
A list of the key machines used in the project. For each machine, list its purpose, location, owner, maintainer, backup strategy, and an estimate of the time it would take to recreate it from scratch. This can really help when assessing the largest physical risks to a project.
Email archives -
An interface for browsing and searching a centralized archive of the messages to email aliases for each project. Creating such an archive saves multiple people from doing the same thing within their own mail clients.
Statistics -
Project statistics can include the number of lines of source code, the top ten committers, the complexity of the code, and the estimated value of the code (e.g., using SLOCCount; see Section 6.5.3). These values are often inaccurate, but are at least entertaining. Historical trends are more useful than absolute values here.
11.3.13. About the Web Site All the other web pages discussed so far contain information about projects and their products. This web page is about the project web site itself:
Sitemap -
What information is available on the web site. This page should be automatically generated.
Changing pages -
The instructions for how to modify a page. These have to be simple, ideally simple enough to add as a footer to the bottom of every page on the web site.
Changing the web site -
A description of how the web site is structured and how to modify the structure of the web site.
Usage statistics -
Statistics about how the web site is used. For example, the most popular pages, the pages no one ever uses, and pages that produce "404 Page Not Found" errors. A list of recently changed pages is also helpful if you are an administrator for the web site trying to monitor what information people most want. The changes to the static parts of the web site can often be tracked using change logs, assuming that these static parts are stored using an SCM tool.
Web tools -
Information about how to run a link checker for the web site and about other web-related tools such as HTML Tidy (http://tidy.sourceforge.net).
Contact details -
An email alias for contacting the people responsible for running the project web site. webmaster or web-admin seem popular. I know of at least one church that uses websexton for this alias.
|
