OVERVIEW OF THE MEMORY MANAGEMENT INFORMATION SYSTEM
overview.infosys
draft doc
richard 1995-08-02
INTRODUCTION
.scope: This document gives an overview of the Memory Management Information
System (InfoSys).
.readership: This document is intended for any Harlequin employee.
Overview
.over: The Memory Management Information database is the home of the Memory
Management Information System, a portable method of tagging and storing
information. Some information is stored in other places, such as HOPE and the
MM Evolution and MM Documentation databases, and these things, while strictly
not part of the InfoSys, are designated by tags and their usage is documented
in MM Information.
.purpose: The final purpose of the Information System is to help the Memory
Management Project achieve its goals. See goal.general. .fun: The system is
for sharing and recording information (requirements, ideas, designs, meeting
records, procedures, guides, papers, etc.).
History
.hist.0: Created. richard 1995-08-02
.hist.1: Note other databases. pekka 2000-05-16
TAGS AND THINGS
.thing: The system stores "things". All entities relevant to the project can
be entered into the system as things, with some standard information about
them. A thing might be a design document, requirement, person, procedure,
meeting, defect, objective, or whatever. A thing is represented by a
"document", and the form of the document is determined by the type of thing.
.tag: Each thing is identified by a unique "tag", such as "book.gilb93" or
"design.general.process.collection". The exact method of choosing a tag
depends on the type of the thing being tagged. A document may contain bindings
of further tags. This document is tagged overview.infosys, and this paragraph
is overview.infosys.tag. See guide.tag.
.tag.just: Tagging provides a way of referring to things in the project. For
example, an implementation may be derived form a particular bit of design, and
meet a certain requirement. Its production may have been guided by a
particular style guide, and it may have followed a certain template. The code
may also follow rules. All these things are tagged, so recording them in the
implementation is easy.
.tag.unambig: Tagging things gives an ordered way of describing all things of
importance to the project, and of referring to them unambiguously. When
discussing some topic in mail, for example, one can justify an idea or
suggestion simply by quoting the tags of the requirements it attempts to
satisfy.
PORTABILITY
.port.plain: Documents stored in the system are formatted as much like plain
text files as possible. We should resist the temptation to use the fancy
features of the implementation. This maintains portability of the system and
the information it contains. We may have to change the implementation, and the
disruption to the project should be kept to a minimum. It should be possible
to perform a simple transformation from, say, the Lotus Notes implementation to
a set of files on a FAT file system.
.port.trans: Having said that, we can use features of the implementation to
help us organize the information in the system. For example, Notes will give
us ways of viewing the contents of the system. It is also OK to use
implementation specific formatting, but only if the document doesn't lose
meaning or usefulness when stripped of that formatting.
COMMON INFORMATION
.common: All things have certain bits of information stored. These are Tag,
Revision, Status, Type, Title, Creator, and CreationTime.
.common.tag: Tag: The unique hierarchical identifier for the thing. Tags
should be made up of the characters A-Z, a-z, 0-9, and hyphen, with elements
separated by dots (periods). The case of characters in a tag is not
significant. Tags will be canonically stored as lower case. Each document
type will define how to choose the tag for that document. In general, the tag
is the name of the object that is tagged, and it is therefore a "noun phrase"
in some sense. For example, a bibliography entry for a book is tagged
"book.xxxyy" and not "bib.xxxyy".
.common.revision: Revision: A revision number for the thing. When the thing is
modified, the revision number should be increased by one. A tag may be
qualified with a revision number (e.g. "process.rights(3)") to indicate which
particular version of the thing is meant. Usually, revisions are increased
when an "accepted" (reviewed) or "draft" document is modified. The new
revision becomes "incomplete" until it is finished, and "draft" until it is
reviewed.
.common.status: Status: This is the stage of processing of the thing,
indicating its progress within the project. New things are "incomplete", but
can become "draft" when the creator thinks they are complete. Draft documents
can be submitted for review, and their status changes as they pass through the
review process. Finally, they become "accepted", indicating that they have
been checked and can be relied upon. See design.infosys.keywords.status for
more details.
.common.type: Type: The generic type is "doc", since all things are documents.
Each document type has a "form" which determines the information stored in the
thing and how it is formatted. Things of type "doc" have the most general
document form -- free text. Where appropriate, there are more specific forms
for other types which attempt to make the information more regular and assist
its processing. For example, bibliography entries are in a particular format,
and include author information. The Lotus Notes implementation implements
forms directly, but they are basically plain text templates. See
design.infosys.keywords.type for more details.
.common.title: Title: The title is a short description of the document in
English. The tag should be enough information for the initiated to figure out
what something is. The title should provide enough information for the
uninitiated, for example, a visitor from another project looking at the system.
.common.creator: Creator: The creator is the person (or people) who created the
document. If the document is being copied from elsewhere (for example, a
pre-existing document or mail message) then it should be the person who created
the information in the first place. When a document is revised, the person or
people who revise it become the creators of a new revision of that document.
The creator should be a person; see type.person and
design.infosys.keywords.person for more details.
.common.creation-time: CreationTime: The time at which the document was
created. Usually this is when the document is entered into the system. If
it's being copied from elsewhere, try to use the original date that the
information was created. When a document is revised, a new revision is
created, and therefore the creation time is the time of the revision.