Document Architecture

Howdy

I have the unenviable task of creating a standard set of
documentation 
that is really an aggregation of information that lives in a
variety
of different places. Now I was wondering what would be the
best way of 
building such pages?

Should rely completely upon the Wiki and use WikiTemplates
to have 
common blocks identified (e.g. hostinfo) or should I try and
snarf
if out from various databases or even some single issue RSS
feed.

Of course this make the documentation difficult to maintain,
but at the 
same time it theoretically is dynamic reflecting whatever
the state
of the various input sources.

The alternative is create a skeleton and let people edit
that and plug 
things in. If I use that method how "ugly" is
having a skeletion
with WikiTemplates in it?
Something like

{}
Text
More Text
{}
More Text
Even More Text
{}
External Links


Or some such?

Please let me know.

Thanks


Ron Hall
Senior Analyst
McGill University
NCS - Enterprise Systems


_______________________________________________
MediaWiki-l mailing list
MediaWiki-lWikimedia.org
http://mail.wikipedia.org/mailman/listinfo/mediawiki-l

On Tuesday 29 August 2006 19:06, Ron Hall wrote:
> Howdy
>
> I have the unenviable task of creating a standard set
of documentation
> that is really an aggregation of information that lives
in a variety
> of different places. Now I was wondering what would be
the best way of
> building such pages?

Wow! I really envy you. I wish my boss would give me the
time to do something 
like that. Sounds like an interesting challenge. (No joke!)

> Should rely completely upon the Wiki and use
WikiTemplates to have
> common blocks identified (e.g. hostinfo) or should I
try and snarf
> if out from various databases or even some single issue
RSS feed.

We have the problem that data is in multiple sources and
going to stay like 
that. For example, customer information, asset management,
trouble tickets, 
and so forth. If the information is already in a database
and you already 
have a front-end for it, I would not necessarily recommend
moving it all into 
the wiki just to have it in one place. 

> Of course this make the documentation difficult to
maintain, but at the
> same time it theoretically is dynamic reflecting
whatever the state
> of the various input sources.

Not necessarily. In fact, in out case, just the opposite is
true. Since the 
asset management and trouble ticket software already has a
front-end that we 
use for other purposes, it it actually easy to maintain. Onr
key aspect is 
defining where each type of data/document belongs. For
example, Outlook 
*could* be used to store customer information and it already
contains 
employee info. However, there would not be any connectivity
to the help desk. 
So, we say all customer information is stored in the help
desk. All asset 
information is stored in the help desk. Although the help
desk *could* be 
used to store instruction on how to configure a piece of HW
or SW, we don't. 
We store that somewhere else. However, the place you store
each *type* of 
information is defined/standardized. In is a misconception
to believe that
standarization immediately means everything in one place. 

> The alternative is create a skeleton and let people
edit that and plug
> things in. If I use that method how "ugly"
is having a skeletion
> with WikiTemplates in it?

We are in the process of implementing it. When the user
starts a new document 
they choose from multiple document types. Each has different
sets of 
information. Basically, these are boilierplates (what I
would call a 
"template"). We don't really use the Wikie
templates.

This way, the user knows what type of information is
expected for each 
document type.  We even have a block on the bottom
"Page Info" for things 
like the expiration date, creator, page owner, and so forth.


Regards,

jimmo

---------------------------------------
"Be more concerned with your character than with your
reputation. Your
character is what you really are while your reputation is
merely what others
think you are." -- John Wooden
---------------------------------------
Be sure to visit the Linux Tutorial:  http://www.linux-tutor
ial.info
_______________________________________________
MediaWiki-l mailing list
MediaWiki-lWikimedia.org
http://mail.wikipedia.org/mailman/listinfo/mediawiki-l