Maintaining dynamic content

Subject: Maintaining dynamic content
From: "Denise Lystad" <LYSTAD -at- lynden -dot- com>
To: "TECHWR-L" <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Wed, 27 Apr 2005 16:40:24 -0700


Thank you so much to all who contributed suggestions!! This list is
great!

I don't know yet which route we will take but here is a compilation of
the responses I received.

1. Multiple-author weblog. Helpdesk personnel can enter info and doc can
edit it. You could set up RSS feeds to enable both sides to subscribe
and be alerted to new postings. Naturally, someone must take charge and
assign roles and monitor that they are being performed. That way
responsibility is shared, but someone IS IN CHARGE. Maybe that role
itself can be put on rotation.

2. Instead of rotating roles, management should decide who owns it, and
then make it part of their performance review.

3. Get a web developer who knows server-side community web apps.

4. In addition to Weblogs, those who are familiar with Wiki might like
to explore
http://www.twiki.org/. According to the home page, "It is a structured
Wiki, typically used to run a project development space, a document
management system, a knowledge base, or any other groupware tool, on an
intranet or on the internet."

5. If any restrictions are to be applied to authorship, will a wiki
work? The premise of a wiki (including twiki) is that, if you can access
it, you can change it. Many wikis devote a good bit of bandwidth to
editing/correction.

6. We currently use a wiki (twiki) to maintain up-to-date information
for our support staff. It is possible to restrict editing capability to
only a certain subset of users. This does not prevent all users from
viewing the information. Refer to
http://twiki.org/cgi-bin/view/TWiki/TWikiAccessControl for more
information.

7. I think the wiki concept is a great one for documentation projects,
especially those where collaboration is important, or where linking of
information is valuable. I use DokuWiki
(http://wiki.splitbrain.org/wiki:dokuwiki) for several documentation
projects, which is described by the author as "a standards compliant,
simple to use Wiki, mainly aimed at creating documentation of any kind."

There also exist converters to transform Microsoft Word files to
DokuWiki markup
(http://www.wakatara.com/blog/index.php/archives/2005/01/17/on-collabora
tive
-simplicity-and-the-word2dokuwiki-macro/) and to convert
OpenOffice/StarOffice to
DokuWiki(http://homepages.paradise.net.nz/hillview/OOo/).

8. For PARROT (Product Assistance Rapid Regional Offsite Technician)
trainees in our MUTT (Most Useful Technology Transfer) program, we've
been using stickies. As part of the program launch, our PARROTs flew to
local supply stores, they had a ball picking out stickies of various
colors and shapes. We tried online purchasing, but our PARROT
teams would flock to ebay, and get caught up in bidding for cuttlebone
and millet gift packs for each other.

We use RBSB (Really Big Stickie Board) as our knowledge repository. When
a PARROT comes up with a modification to a cheat sheet, they place their
new stickie over the previous one. This has worked well for us in
tracking and identifying new issues, and management has no problem
accessing the history of each cheat sheet.

To further enable users of the program, we've installed several watering
cups on the RBSB, hoping to entice our PARROTs to use the RBSB as an
ersatz knowledge incubator, a tech support waterhole.

Our help desk has improved in several ways. Our PARROTs have memorized
the cheat sheets, which is a good thing, as they have a habit of
shredding off important parts when they become nervous and over-worked.
As the litter in each cubicle increases with these stickie shards,
management can readily see when it is time for a water
change.

Occasionally we lose a PARROT when the weather is nice and the front
door has been left open, but we are confident that each new PARROT
trainee will assume ownership of their territory, and find perfect
responses for each customer in need.

9. Put another way, not all web-based, collaborative, content management
tools are wikis: most are not. That *anyone* may edit the content is
what makes a wiki a wiki. 'wiki', the buzzword, is running a bit amok.

I don't mean to say that if it's not exposed to the universe, it's not a
wiki. Private groups can operate a wiki. Rather, the idea is that once
you're in, there's no user hierarchy. Anyone may post, anyone may edit.
Anything. Live. Nobody's *the* editor because everyone's an editor.

10. My current fascination is with Drupal. Yes, you might use about 20%
of Drupal's functionality to operate a blog, but you could also use it
to replicate NYTimes.com. And I mean *all* of NYTimes.com: elaborate
content taxonomy, archiving, access control, editorial workflow, forums,
email to a friend, email alerts, for-fee content access ... you name it.
There's even a wiki module. And anyone's free to learn the API and
create custom modules.

http://drupal.org/project/releases

(Drupal, WordPress, and TextPattern are FOSS; pMachine has a free
version. Of these [which are php/MySQL/Apache-based], Drupal is best
suited to more elaborate sites. Another good choice is Plone, though
you'll need to be running the python-based Zope Application Server.)

Imagination is the only limit on what it can do, yet I can still hand it
over confidently to the next webmaster.

Last thing: quality of markup. XHTML validity and well-formedness can
break in two areas: the templates ('themes') and the user-provided
content. I make sure the templated output is well-formed, and accept
user input in John Gruber's 'Markdown' pseudomarkup -- which doesn't
know how to be malformed. Now that each page is well-formed XHTML
(hence XML) it can be parsed and refactored forever. Since all content
is a database record, though, refactoring isn't a problem anyhow.

I have personal knowledge that what Denise wants to do is eminently
achievable -- and comparatively easy -- using freely available tools and
frameworks. No per-seat costs, no desktop applications. The browser is
the GUI. You could have such a system up in two weeks.

11. Your questions are related to exactly what I was hired to do, so
I'll tell you a little about our process. We are using a series of
databases and .asp pages on our company intranet to track calls and
technical entries. Depending on your software application, this process
may or may not work.

We have two main areas of our help desk system: a technical library, and
a trouble-ticket system, know around here as CART, or computer automated
request tool. The technical library is a series of .asp web pages that
contains our technical information. When our call center receives a
call, they create a trouble-ticket in CART and add notes, solutions, etc
as they track the fix. They are supposed to be searching the technical
library and if a fix is available, noting in the trouble ticket what fix
they used and the intranet address where it is located. If a fix is not
documented in the technical library, they escalate the call to our
second level support. Once second level support finds the solution, they
add notes to the trouble ticket and close the request. If a request
gets to second level support, it means it is not documented in our
technical library.

This is where I come in. When second or third level support closes a
request, the request is sent to a "documentation pending" area of our
intranet. This area allows me to review the second and third level
requests that are closed and determine if the solution needs to be added
to our technical library. I either officially close the request, moving
it from documentation pending, or I request more information and add it
to our
technical library.

We also have an email template for solutions on problems that are not
related to a particular call. Everyone in the department has the
template, which consists of symptoms, causes, solutions, keywords and
our authorization level. The help desk fills out the template and emails
the information to me. I then add it to the library.

So that's our process. I'll get to your questions now.

1. Who determines whether a new cheat sheet should be created? I do! All
requests that do not have documentation in the technical library come to
me. It is my decision to decide if the solution should be added to the
library or not. Information that is sent via email always gets added. I
guess in part it is a joint effort between me and the helpdesk.

2. Who makes sure the existing cheat sheets are kept up-to-date? How
often are they checked? I am responsible for keeping everything
up-to-date, with help from the help desk. It is my plan to review
everything every six months. However, that said, if I don't know that
anything has changed, I assume they are up-to-date. I'm trying to get my
department to keep me informed of all changes around here so that I
always know what is going on.

3. Who writes the cheat sheets? I do!

4. Should authoring access to the cheat sheets be restricted? We don't
restrict access to the development side of the documentation. It is
pretty much understood that I do the writing and editing. No one else
wants to do it anyway, so this is not exactly an issue. However, if in
the future the call center or anyone else starts modifying the
documentation on their own, I probably will request that we restrict
access.

12. I also maintain and write documentation for our Help Desk and for
the rest of our IS staff. We currently do not publish the information to
our users, but sometimes the Help Desk copies and pastes the info into
an email that is sent to a user. We have all of our documentation on a
Web server and use MS IIS to search the documents. I also have an Access
database that I keep track of the Section, date created/modified, title,
SME, creation time, and modified time. That way I can search it for last
modified date to determine when a document is ready for editing.
Although I would like documents to be edited every 6 months or 1 year,
it is often difficult to get SME to spend time on editing.
Unfortunately, I have quite a few documents that are out-dated and need
revision.

We have 3 types of documents that are posted to our Knowledge Base:
Problem-Cause-Solution, Procedural and Information Sheets. Most of the
time the Subject Matter experts initiate new documents. The Help Desk
creates some of the Problem-Cause-Solutions docs.

1. Who determines whether a new cheat sheet should be created? The HD if
it is a problem that they need resolved or a procedure they need
instructions for.
4. Should authoring access to the cheat sheets be restricted?
Definitely. There should be a group designated as authors and that group
should have some type of style sheet that they use for editing. That
will keep the Cheat Sheets consistent.

Thanks again!

Denise Lystad
Lynden Incorporated


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

WEBWORKS FINALDRAFT - EDIT AND REVIEW, REDEFINED
Accelerate the document lifecycle with full online discussions and unique feedback-management capabilities. Unlimited, efficient reviews for Word
and FrameMaker authors. Live, online demo:
http://www.webworks.com/techwr-l

---
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- techwr-l -dot- com
Send administrative questions to lisa -at- techwr-l -dot- com -dot- Visit
http://www.techwr-l.com/techwhirl/ for more resources and info.



Follow-Ups:

Previous by Author: How do you maintain dynamic material
Next by Author: Re: Exempt vs. Non-Exempt
Previous by Thread: The importance of good documentation
Next by Thread: [rant] Word styles and templates


What this post helpful? Share it with friends and colleagues:


Sponsored Ads