Re: web apps / sql / designing a documentation delivery system...

Subject: Re: web apps / sql / designing a documentation delivery system...
From: "Jeanne A. E. DeVoto" <jaed -at- jaedworks -dot- com>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Wed, 29 Mar 2000 21:28:42 -0800

At 10:31 AM -0800 3/29/2000, gyaker -at- csc -dot- com wrote:
>Lets say your client asked you to put all of their documents on the web and
>create a web site where their customers could access all of the latest
>information on their product or service. How would this be set up and what
>fundamental concepts do you need to learn?

You suggest a number of specific technologies and specific languages you'd
need to know. I recommend backing up a bit and looking first at the
requirements of the situation, and going from there to figure out what you
need to fullfill those requirements.

Start with the documents.How many of them are there? How often do they
change? Is it reasonable for one person, the webmaster, to change them by
hand, or will the document maintainers need to do the changes themselves?

What format are these documents presented in? Are they plain text/PDF/HTML?

What form of organization makes the most sense? Will users need to search
through the text of the documents? Or will a simple hierarchical structure
("Here are the document files for our Acme 1.2 software") suffice?

What web resources are available? Does the organization already have one or
more web servers, and can you obtain space on said servers? How much
traffic do you expect - how many people are going to be accessing these
documents on a typical day?

Armed with information such as this, you can start answering questions
about your needs for this project:

- Can you update the documentation by hand, or will you need to provide a
front end for document maintainers who don't know HTML or the directory
structure, to let them check in changes?
- Will you need to convert the documents to another format, or can you
simply put them up on the server as-is?
- Can you create simple static HTML files to organize the information, or
will you require a database? Do you need to set up a search engine?
- Can you obtain space on an existing server, or will you need to set up a
server of your own?

From the answers to this second set of questions, you can derive a list of
your specific technical needs, and you will then be in a position to decide
what technologies you need to know in order to satisfy them.

You might end up with, at one extreme, a directory on an existing company
server, containing a simple list of available documents, which you update
whenever a new version appears: for this, all you need is a bit of HTML and
the ability to upload documents.

At the other extreme, you could end up running your own server, with the
documentation held in a database as XML from which a number of formats can
be automatically generated, and which provides a front end to writers
authorized to change the documents in the database. It all depends on what
you're working with and how fancy you want/need to get.

jeanne a. e. devoto ~ jaed -at- jaedworks -dot- com

Currently seeking technical-writing contracts:

Previous by Author: Re: Estimating Online Help Schedule
Next by Author: Is indenting subheadings and subtext current practice? Is it useful?
Previous by Thread: web apps / sql / designing a documentation delivery system...
Next by Thread: Tech writing interview

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

Sponsored Ads