Brain-dead-simple doc "management" on a self-service intranet [long]

[Dick Margulis <margulis -at- fiam -dot- net>]

Our intranet site sucked. This was largely my fault, because the guy who 
designed it worked for me (before the dot-bust), and I was not 
sufficiently, um, firm in supervising him. We've lived with it since 
then, but nobody--least of all me--has been happy about it.

Well, the grumbling reached the level [the CEO level] that it was clear 
I had to put some time into a radical redesign.

In addition, although I've been trying for a year to free up some 
dollars for a cheap Web-based doc management system, that keeps getting 
pushed out and our informal document heap is threatening to collapse on 
itself. (This is in reference to business documents, not technical 
documents, which are managed just fine.) My customers are sales and 
marketing types for the most part, and linear thinking is not their 
strong suit. "Process" is a four-letter word, and any procedure that 
takes more than four clicks is likely to be delegated to someone else, 
possibly me.

So I noodled a bit, and I'm really pleased with the result. So far 
everyone I've trotted it out to (it's still officially in beta), has 
liked it, too. So here's a description of what I came up with. Maybe it 
will give you some ideas, too.

Don't bother to tell me that if I had done some research I probably 
could have put the whole thing together in an hour using Wiki or 
something like that. I don't want to know about it, and besides I had 
fun writing code for a few days.

LINKING

The old site was designed in a frameset. This presented a problem in 
that you could not easily email someone a link to a page or document. 
Instead you had to send navigation instructions (home > operations > 
templates, for example).

The new site is designed in a table. Every page has its own URL visible 
in the address bar.

SEARCH

A problem with the old site was that even though there was a perfectly 
serviceable site search tool, it was not prominently displayed. There 
was a small, indistinct magnifying glass icon in the highly designed 
page header, and there was a menu item one level down (if you knew where 
to look).

The new design has a boldly labeled search box as the top left item in 
the solid-colored head cell of every page. Typical reaction: "Wow! 
You've added a search tool. That's great. I hated that we couldn't 
search before." (Of course they could, but nobody realized it.)

This is an ASP site running under IIS, and the site uses the built-in 
IIS search engine. I included a link next to the search box to "Search 
tips"; I cleaned up the HTML in Microsoft's search syntax page and 
attached the site CSS, so it looks like part of the site. I recommend 
this search engine for intranet sites; it's quite efficient.

ORGANIZATION

The old site was organized into directories by department. Of course 
companies reorganize all the time, and ours is no exception. So the 
existing directory structure is a snapshot frozen in time of an 
organization that no longer resembles the company.

These directories had specific NT Security permissions assigned to them 
so that designated individuals had write privileges. These were the 
individuals delegated by their department managers to be trained in 
maintaining their department's pages. This proved a bureaucratic 
nightmare as personnel turned over and maintenance for the whole site 
devolved to me.

Each of these directories had subdirectories for pages, includes, 
images, and documents. Yikes!

The new site has a single directory for all pages, a single includes 
directory, a single images directory (although it has subdirectories for 
my convenience) and a single documents directory (more about that 
later). Basically, there is only one place to look for anything, and if 
the company is reorganized, the biggest change will be changing the 
names of links in the header.

There are no permissions issues. This is a self-service site. Anyone in 
the company is free to add or edit pages and upload or update documents. 
There is full accountability, because any such action records the name 
and date; and only the webmaster (that's me) can delete anything.

PAGE TEMPLATE

The old site had a "template.htm" file in each of the departmental 
directories. This was a blank HTML page with a CSS attached. Basically, 
it was tabula rasa, and thus none of the departmental designees had any 
real guidelines. Consequently, there was no consistency through the site 
in terms of how things were organized or displayed.

The new site has a single template, available to everyone (there's a 
"Create or update a page" link in the header). This template is simple 
and sufficiently flexible for the purpose, but not freeform. If any 
special-purpose pages are needed, I'll have to make them; but the 
template will meet most needs. It is a table. The top row is the default 
page header (an include file that can be updated to reflect changes in 
departmental names, number, or organization). The next row has two 
cells. On the left you can compose text describing the page's contents 
and use. On the right is an include file that lists links to bookmarks 
on the page (automatically generated for all headings) and to other 
pages you select (from a list generated from a database table). The next 
row spans the page and is an include file that generates a table of 
documents categorized under headings you create. At the bottom is a 
footer (another include file) that reinforces the confidential nature of 
the materials on the site.

CREATING A PAGE

I built a poor man's wizard. On the first page, you select an existing 
page as a model or the template, choose a filename to save as (or leave 
blank to update an existing page) specify the page title (or leave the 
existing title unchanged), and specify the page's H1 headline (or leave 
the existing heading unchanged). Then you have three ways to create copy 
for the description cell. You can leave existing copy unchanged; you can 
paste in HTML (with warnings to dissuade amateurs); or you can write up 
to five paragraphs by selecting a paragraph style (H2, H3, lede 
paragraph, or regular paragraph) and typing text.

On the next page, you select other site pages you want to display links 
to. Then you write (or edit existing) subheading for the document 
listing, and you put these in the sequence you want them displayed.

The final step is attaching documents to the page, but that's done by 
uploading or updating documents, not as part of designing the page. So 
essentially you're done.

The output is a new (or updated) ASP file. It has a comment at the end 
of the file that includes a date and time stamp and your name. The 
filename goes into the database so your page is available for linking 
from other pages. The subheadings are in the database so the document 
table can be built for the page.

DOC "MANAGEMENT"

I use the term loosely, because this is really a pretty poor, 
feature-deficient excuse. It seems to be sufficient for our immediate 
needs, though.

The page header has an "Upload a doc" link and an "Update a doc" link. 
The database has a table that ties a display name to a filename and 
notes who last changed the doc (from the server variable, not from user 
input).

When you upload a document, you give it a display name. This can be 
lengthy and include spaces and HTML entities. I haven't tested just 
typing in ANSI characters like quotes and dashes, but they'd probably 
work, too, as long as everyone sticks to IE. Then you write whatever 
comments you want to display next to the document on the page listings. 
This can be as short or long as necessary and is optional. You select a 
sensitivity level (how confidential it is, in other words). Finally, you 
navigate to the document on your hard drive and click to upload. 
(ASPupload, Persits Software, $149, recommended). A progress bar tracks 
the upload for you.

What I do on the back end after the upload to a temp directory is rename 
your file. I prepend a system date and time stamp and I replace spaces 
with uderscores. The date and time stamp ensures the uniqueness of the 
filename, even if you later upload a file with the same name. I also 
record in the database the updated filename and the username. What you 
can never change (although I can) is the display name of the file. This 
is what remains invariant as people upload new versions of a document.

After you upload the document, the next step is to say where you want 
the document to be shown. On the next page of the upload/update wizard, 
you see a complete list of all the pages in the site with the category 
subheads for documents. You check as many of these subheads as you wish, 
and your document will be displayed, alphabetically by display name, 
under each of those subheads.

DISPLAYING THE DOCUMENTS

In building the table to display the documents on user-created pages, 
each document shows the display name as a link (click to display in the 
browser or right click to download). To the left of the link is a small 
down arrow graphic (single left click to download the document, part of 
the ASPupload package from Persits) Under the display name in tiny type 
is the following information: Who uploaded the document and on what 
date; label ("size:"); 10x10 square in a solid color (green/yellow/red) 
to represent the size, with a tooltip giving the exact file size; label 
("sensitivity"); 10x10 square in a solid color to represent the 
sensitivity, with a tool tip spelling out the exact meaning of the color 
code. To the right of all this is the comment field, top-aligned with 
the doc name but spanning both rows.

At the bottom of the table is a legend that spells out what the colors 
mean and what the download arrow means. This, too, is built from the 
database, so the range of sensitivity codes can be expanded if some CFO 
comes up with a new need three years from now, for example.

RISKS

Some disgruntled person could wipe out the content of all the pages on 
the site or could add a page with some sort of scurrilous content. We'd 
know who did it, but I should add a bit of code to save a BAK version of 
any page that gets overwritten (it's on my to-do list). People can 
upload really crappy documents, but then someone else can update them. 
Document versions are not deleted, so if somebody inadvertently replaces 
a final version of a document with an earlier draft, say, I can make a 
manual change in the database to point to the correct version--assuming 
someone alerts me.

CONCLUSION

I'm no longer a gatekeeper. I will no longer have to field email 
requests to "throw this doc up on the intranet somewhere," followed by 
"I don't understand how the site is organized and I can't find any 
documents I need." The site is as democratic as it can be. People are 
accountable (because their name is attached to everything the upload or 
create), so I don't get blamed for the silliness of their organizational 
schemes. I'm likin' it.

Dick


^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

ROBOHELP X5 - ALL NEW VERSION!! 

Have you tried the latest in Help Authoring from RoboHelp?
Try ROBOHELP X5 for Free - Now with Word 2003 support, Content 
Management, Multi-Author support, PDF and XML support and much more! 

Download a free trial today: http://www.ehelp.com/techwr-l4

---
You are currently subscribed to techwr-l as:
archiver -at- techwr-l -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot-  Visit
http://www.raycomm.com/techwhirl/ for more resources and info.