Managing Web Content Using Microsoft Visual SourceSafe
Revised: January 1997
A multitude of files and components make up the pages of Microsoft's corporate Web site, http://www.microsoft.com/, authored by hundreds of people. Maintaining a Web site of this magnitude is not simply a matter of writing HTML syntax: It is a large-scale development, management, and coordination task. The Visual SourceSafe™ team has developed an approach based on the existing content management capabilities in Visual SourceSafe to automate and securely track the many changes that occur within the group's Web content.
Since the original publishing of this document in January 1996, other groups at Microsoft who submit content to www.microsoft.com have started using Visual SourceSafe to manage their Web content. The Visual Basic®, Microsoft® Visual Basic Scripting Edition (VBScript), Visual FoxPro®, Internet Control Pack, and Visual SourceSafe Web pages, among others, are all managed using Visual SourceSafe. This paper outlines a process that utilizes Visual SourceSafe sharing, keyword embedding, link checking, content publishing, site map generating, and shadow directory capabilities to provide a solution to Web content management today.
Many people work together to create, support, and update material for the Microsoft Web site. Combining a large number of documents, people, and updates creates a complexity that is not easily managed without the help of an automated solution.
Below is a simplified example of the process used for submitting and updating Web page content for inclusion in the Microsoft Web, as illustrated in Figure 1:
- The process begins with a team of content developers collecting and authoring documents that are written natively in HTML or converted using Internet Assistant for Microsoft Word. In addition to HTML files, often script language files and graphics format files are involved. These files are stored in logical directories on a network server to which each member of the team has access.
- After modifications are made to existing Web pages, the revised files are copied to another server that is managed by a different group of people who test the files for broken links, proper syntax, and so on. Files are submitted by many product groups to this central testing group.
- If bugs are found in the HTML or code files received from a group, the testing team communicates this back to the product team, which resolves the problem and reposts the Web page on the testing server.
- Once tested and successfully debugged, the directories are copied to the main Microsoft Internet Information Server where the external world can link to Microsoft via the Internet.
Figure 1. Process for submitting and updating content for the Microsoft Web site
Inherent in this process are three basic requirements:
- HTML and script writers must be able to create and self-test their files in a rapid-prototyping style of development. They must be able to save their changes and see immediately what effect the changes had on the browser-rendered version of the file.
- Writers and programmers must also be able to permanently save versions of their files as the rapid-prototyping process proceeds.
- The central testing group must be able to quickly test content submitted by the product groups and then deploy the final files—sometimes to multiple servers.
The challenge faced by Microsoft, and other teams or corporations, who are instituting similar systems, is to manage this rapidly expanding body of information. HTML writers should focus on creating content; testers should focus on testing links as rapidly as possible and getting updated information onto the server; and all of the parties concerned should spend as little time as possible asking questions such as "Who worked on this document?", "Where should I copy it to?", and "What happened to the version that worked?" Many groups at Microsoft use Visual SourceSafe features, such as shadow directories, keyword expansion, deploy, link checking, and sharing today to automate file tracking and versioning to keep the system manageable.
The first step to successfully using Visual SourceSafe as a Web management tool is to organize your Web site into a logical hierarchy of projects. A typical Web site is organized as a main directory, with a starting page (often called DEFAULT.HTM or INDEX.HTML) and supporting pages and subdirectories stored in a directory tree on the Web server. To start using Visual SourceSafe as a Web tool, create this folder structure in the Visual SourceSafe Explorer and then add your Web files to the SourceSafe project tree so that it mirrors your directory tree. (This can be done easily by dragging a folder from the Windows® 95 Explorer into the SourceSafe Explorer.)
In Visual SourceSafe, these relationships are represented by a SourceSafe project tree that mirrors the directory hierarchy exactly. Figure 2 shows an actual screen from the Visual SourceSafe Explorer, showing the database used by the Visual SourceSafe Web team. This screen shot shows the project named "External Web," which is the sample project we will be discussing in this paper. (The "Internal Web" project is simply a different Web site used internally over the company's intranet.)
Figure 2. The Visual SourceSafe Explorer window
Under "External Web" (which represents the main URL root directory) is a SourceSafe project called "Introducing Microsoft Visual SourceSafe." This subproject contains overview information about Visual SourceSafe—things like white papers, descriptions of version control advantages, and others. As the screen illustration above shows, one file—SOTHER.HTM—is currently checked out by a user named Stevenj. When Stevenj clicked "Check Out" for this file, a copy was made in his local working directory on his computer. He is now editing this file locally. When he completes his changes, he will check the file back into Visual SourceSafe, thus making his changes available for the rest of the team.
The benefits of using Visual SourceSafe in this way are the standard benefits that version control has always offered to professional developers. It helps coordinate the team, by keeping track of which people are working on which files. Visual SourceSafe also keeps track of old versions of all the files in a very disk-efficient way, making it easy to revert to an old state of a file, or of an entire project. Version and source control are basic and vital benefits of Visual SourceSafe, but these are only the beginning of Visual SourceSafe's capabilities that help you with your Web site.
In addition to the "External Web" project discussed above, there is another project in Visual SourceSafe representing the "Internal Web." Like the external Web, this project consists of a number of subprojects and files (not shown in Figure 3) that reflect the hierarchy of directories on the SourceSafe Web site. However, this project builds a completely different site—the SourceSafe internal Web site, which is available only to other Microsoft groups. This Web site is hosted on a completely different server from the external Web site. In addition, some of the files between the two sites differ, although most are the same. When a developer modifies a file, that modification may affect one site, or it may affect both—and it is obviously critical that the file is copied to the appropriate sites!
Sharing is the Visual SourceSafe feature that automates tracking the simultaneous Webs. Sharing simply means that, in Visual SourceSafe, one file can exist in multiple projects at the same time. For instance, the file "SWHITE.htm" is used on both the external and internal Web sites—in both cases, the file exists in subdirectories called "Techinfo". In Visual SourceSafe, the file is shared between the "Techinfo" subprojects under both the "External Web" and "Internal Web" projects. Visual SourceSafe stores only one copy of the file internally—so whenever a change is made to this file in either project, that change is automatically reflected in the other project as well.
The benefit is that the SourceSafe developers, in general, do not have to worry about multiple Webs. They can change a file once, and know that the change will propagate to both Webs if it should, and will only affect one Web if the file is only used once—automatically.
No one wants to publish content with a bad link to a live Web server. Doing so reflects an unprofessional image in the eyes of the person browsing your site. Visual SourceSafe 5.0 includes a feature to check your hyperlinks, providing an easy way to test for broken hyperlinks before you publish content to the server. The Check Hyperlinks feature works against your working directory or the shared project on the server, giving you a concise report outlining any internal broken hyperlinks. What's more, this feature is based upon the registered IFilter ActiveX® interface, so you can add any custom link checking functionality supported by the interface.
So far, each developer is working in a local working directory on his/her hard drive, and checking in content to the shared repository on the central test group's server. Visual SourceSafe 5.0 now gives you a way to publish your updated content to a test server, or a live Web server, using the Deploy command. The Deploy command is capable of working across corporate proxy servers (firewalls), or deploying Web content to several different Web servers at once.
The Visual SourceSafe administrator configures the Deploy path and other related variables from the Visual SourceSafe Administration program. Inside the Administration program, you may tag a Visual SourceSafe project as representing a Web site. Once this association has been established, the administrator can set other options that apply to the target Web server directory, proxy server settings, and so on. After the appropriate settings have been established, authorized users can publish content with the click of a button from inside Visual SourceSafe.
The Deploy command is an excellent way to publish your content to a live Web server. The Shadow Directory feature in Visual SourceSafe is another feature often used to publish content to an internal staging or test server. Once set by the Visual SourceSafe administrator, a shadow directory is a central directory on a server that always echoes the contents of a project. Hence, whenever a developer updates a file in a Visual SourceSafe project, that file is automatically copied to the shadow directory.
In our example, the Visual SourceSafe "External Web" project is shadowed to the drop point for the central testing team, and the "Internal Web" is shadowed to the drop point for the internal tests. These drop points can act as miniature Web sites purely for testing purposes, and can also be run through automated testing utilities. Either way, once they are approved, these directories can be copied to the actual Web servers. This can be done by having the test team use Visual SourceSafe's Deploy command.
Note, at this point, how much happens automatically when a developer clicks "Check In"! The file is copied from the working directory on the developer's hard drive, into the Visual SourceSafe project. If the file is shared, this change automatically affects both the internal and external projects. Then the new file is copied into the shadow directories for one or both of the projects, where it will be tested and deployed.
Figure 3. Testing and deployment process
A site map is a list of hyperlinks to your Web site's contents—an online table of contents, if you will. Usability studies have shown that a site is an extremely useful navigation mechanism for most Web sites. Visual SourceSafe 5.0 makes the creation of a site map for your Web site as easy as choosing a menu command. When you choose Create Site Map from the Web menu in Visual SourceSafe, Visual SourceSafe will create a new HTML file and write out a list that includes jumps to all the HTML files within your Web site project. The file created by Visual SourceSafe is named according to a setting made by your Visual SourceSafe administrator, and is pretty basic HTML. You can customize this file, with a different background color, for example, by adding the file to your Visual SourceSafe Web project and then editing the HTML in the file. This makes it easy for you to have the site map file match the flavor of other pages at your site.
Another Visual SourceSafe feature that is particularly useful for Web development is keyword expansion. Visual SourceSafe has the ability to embed certain version control information directly into a text file.
As an example, suppose that a tester in the centralized group finds a broken link. That file will not be deployed to the central Web. Instead, the developer must be notified so the file can be fixed. So the new tracking problem is how does the tester find and communicate with the developer?
The answer is easy if the developer puts the following line at the top of each HTML file:
<!--$Header: /Juniper/Docs/External Web/techinfo/vssWeb.htm 10 3/27/97 11:56a Stevenj $-->
The syntax "$Header: /Juniper/Docs/External Web/techinfo/vssWeb.htm 10 3/27/97 11:56a Stevenj $" is a SourceSafe keyword. When the file is checked in, Visual SourceSafe will automatically fill in the full SourceSafe project path of the file, the version number, the date/time, and the user who is checking it in. So the resulting line might look like this:
<!--$Header: /Juniper/Docs/External Web/techinfo/vssWeb.htm 10 3/27/97 11:56a Stevenj $/Documents/External Web/DEFAULT.HTM, 4, 12/1/95, Stevenj $-->
The angle brackets, exclamation point, and dashes at either end make this an HTML comment, which will be ignored by Web browsers. But the tester who finds the bug can contact Stevenj and specify the exact file (with the Visual SourceSafe project path) and version number that has the bug!
Have you ever seen Web pages with the phrase "Last updated on: MM/DD/YY" on them? Another novel use of Visual SourceSafe keywords is to automate the process of keeping these dates current. Visual SourceSafe 5.0 allows you to specify keywords for use in HTML files that will update these dates whenever you check the file in. You won't forget to update these dates any longer!
The Bottom Line
Visual SourceSafe helps automate the process of managing large, team-based projects. The file sharing, shadow directory, and keyword expansion features, combined with Visual SourceSafe's intuitive interface and project-oriented design, make it a powerful addition to the environment of Web authoring teams. More information on the Visual SourceSafe product may be obtained via the Internet at http://msdn.microsoft.com/ssafe/ or by contacting Microsoft technical sales at (800) 426-9400 (U.S. only) or a local Microsoft reseller near you.