Document Architecture

[Ron Hall]

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

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


Or some such?

Please let me know.

Thanks


Ron Hall
Senior Analyst
McGill University
NCS - Enterprise Systems


_______________________________________________
MediaWiki-l mailing list
[hidden email]
http://mail.wikipedia.org/mailman/listinfo/mediawiki-l

[James Mohr-3]

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-tutorial.info
_______________________________________________
MediaWiki-l mailing list
[hidden email]
http://mail.wikipedia.org/mailman/listinfo/mediawiki-l