As noted in the message

Date: Tue, 30 Jan 1996 08:05:57 -0400 (AST)
To: helpdoc@chebucto.ns.ca
Cc: csuite-dev@chebucto.ns.ca
Subject: Strategy - User Documentation

An overall documentation strategy is evolving and input from interested groups and individuals is invited.

The strategy includes:

- the development of a body of 'narrative' documents that can be implemented widely (including other community/freenets using a variety of software packages).

This portability will require....

...the documentation must be easily customized to reflect the local site. This generally relates to the consistent use of 'site identifiers' such as "Chebucto Community Net" or "CCN".

Either narrative documents...

- totally exclude site references or...
- limit the use of references to site identifiers that can be easily replaced with the 'local identifier'.
Although in some ways it would be tempting to completely eliminated site identifiers from narrative documents it is likely that this carries too large an investment in re-writing to be manageable at this time.

This would leave us implementing a consistent identifier (model) that is suitable for the largest possible number of sites.

Use of 'replacables...'

Currently CSuite is being distributed with two 'system wide' variables... that, here at Chebucto are (set to...)

FULL_NAME="Chebucto Community Net"
SHORT_NAME="CCN"

User Documentation (to this point) has not implemented the use of site identifiers consistently, or taken advantage of these system variables. We have some instances of "Chebucto Community Network", "Chebucto" and even some holdovers from the 'Freenet' days.

(we can clean up the inconsistencies quite quickly and easily once we decide which direction we want to proceed.)

The question then is...

are two forms enough or do we want to add... for example

FAMILIAR_NAME="Chebucto"
ADDRESS_NAME="chebucto.ns.ca"
WEB_NAME="www.chebucto.ns.ca"

At some sites, a familiar name might not be implemented but here in Nova Scotia 'Chebucto' (as an example) can be used without confusion.

Sites that do not use a 'familiar' identifier could set...

FAMILIAR_NAME=$SHORT_NAME

A potential inconsistency involves the use of the identifier to represent both the organizational 'entity', and the 'system'... this raises the possibility of using...

ORGANIZATION_NAME="some org"
SYSTEM_NAME="some system"

If as a group we are relying on volunteers to contribute to a common document base we should ensure the writing is not too onerous a process.
You can see why I have considered eliminating site identifiers from narrative documents... ;-)
[Index]