Clone

HTTPS: git clone https://vervis.peers.community/repos/yEzqv

SSH: git clone USERNAME@vervis.peers.community:yEzqv

Branches

master

description-convention.mdwn

Description Convention

All 4 core Idan files are written, but something is missing: There are no descriptions. Each smaoin:Resource may have a nli:description attached to it as a nli:Text, and it should describe the resource in words. The purpose is simply to explain to humans the meaning of the resource. For example:

Explain the role of the Person class, so people know each person should be a member of it
Explain the role of the friendship property, so people know each two friends should have this property
Explain the role of some object, so people know what it is in case the statements don’t describe it well enough

The question is, how do I write the descriptions in a consistent way? I need patterns for:

Namespaces
Classes
Properties

First, here are some guidelines:

No redundancy: Don’t state information already stated in the statements or in the nli:name of the resource
Compactness: Don’t tell long stories, just describe the object in a minimal way

Now let’s start.

Namespaces

What do we say about a namespace? Basically it’s just a group of labeled objects, serving to help humans refer to those objects. Their description should not describe the ontology they represent, because an ontology is an entirely different concept: It’s a vocabulary for a specific domain of knowledge. A namespace is just a technical practical tool, without any meaning of its own.

Therefore, it makes sense to explain in words something like “This namespace contains the components of ontology XYZ”. If there’s no ontology, just explain what it’s supposed to contain, e.g. “Language objects”. But let’s make the sentence minimal. Start with the word “contains”.

Example for ontology:

“Contains the components of the XYZ ontology”

Example without ontology:

“Contains natural (human) language definitions”

Classes

I need to document a lot of classes. How do I write a short informative description? It seems the natural way to describe kinds of things is by basing the description on something more familiar. Example:

Q: What is an elephant? A: It’s a large four-legged grey-skinned mammal found in Africa and in Asia.

Do you see this? We basically said “Class Elephant is a special case of Mammal, which has properties X, Y and Z”. We took a base class, and explained how our subclass derived from it is special.

I will use the same kind of description. But sometimes it’s impossible, e.g. when defining things not based on anything else. In those cases, I’ll use the minimal part of the sentence. Just the subject. Example:

An Entity is an atomic concept or thing; everything you can use as a statement identifier, subject predicate or object is an Entity.
Entity is the class of all atomic unique distinguishable things; everything you can use as a statement identifier, subject predicate or object is an Entity.
An atomic concept or thing. Everything you can use as a statement identifier, subject predicate or object.

I will be using the third kind.

Note that the first sentence is of the same kind seen above: We take a base class - concept, thing - and specialize it with “atomic”. The second one is however different.

Properties

Again, I prefer a minimal informative description. For example: “The subject language has the object language as a dialect.” Don’t begin a description with things like “This property expresses the relation between X and Y representing the…” Instead get straight to the point. “Represents group membership between the group (object) and the member (subject).”

There are many many properties… let’s start.

Done.

[See repo JSON]