...
| Document Properties Marker |
|---|
|
| Short Description | Glossary items are part of the domain glossary for the project. Glossaries support the team to use terms of the domain consistently in conversations and documentation. |
|---|
|
| | Doctype | doctype | hide |
|---|
| Name | Glossary Item |
|---|
|
| | Audience | | Name List |
|---|
| doctype | role |
|---|
| render-no-hits-as-blank | true |
|---|
| property | Audience |
|---|
|
|
|---|
|
| | Documentation Type | | Name List |
|---|
| doctype | doctype-type |
|---|
| render-no-hits-as-blank | true |
|---|
| names | Q1 - Process |
|---|
| property | Documentation Type |
|---|
|
|
|---|
|
| | Categories | | Name List |
|---|
| doctype | category |
|---|
| render-no-hits-as-blank | true |
|---|
| names | / Document / Entity |
|---|
| property | Categories |
|---|
|
|
|---|
|
| | Iteration | | hide |
|---|
| Sort Key | | hide |
|---|
|
| Section |
|---|
| index | true |
|---|
| title | Description |
|---|
|
It is important for a project to establish a common understanding the terms of its core domain. It may also be helpful to compile definitions, designations, and rough sketches for terms of secondary domains. This provides the basis for preventing misunderstanding or misuse of terms in the documentation, code or communication. Teams must not be scared to describe terms. In project it is usually not necessary and often impracticable to define with water-proofed clarity. Keep in mind that the goal is a common understanding which typically evolves during the course of the project. This is especially true for glossaries that are used within the project by the team and associated experts. It may call for a different approach if the glossary is publicly available. |
...
| Section |
|---|
|
| Transclusion |
|---|
| document | Note Box referencing common Document Properties |
|---|
| ids | Box |
|---|
| |
| Section |
|---|
level | 2 |
|---|
| Allows to organize glossary items by a doctype specific type using Glossary Item Type. |
| Section |
|---|
| A abbreviation commonly used for the term. Defaults to the short name. |
| Section |
|---|
| title | Linguistic Information |
|---|
| Provide linguistic information, such as genus or pronunciation, for the term. |
| Section |
|---|
|
| Version Box |
|---|
| Replaced by the Linguistic Information property. |
Helps Helps to categorize a term to be a noun (concept) or a verb (process-word). | Note Box |
|---|
You may replace the selection macro with the Name List Macro and add other or additional word types. |
|
| Section |
|---|
|
| Version Box |
|---|
| Replaced by the Relation property. |
State the domain within which the term is used. Terms may be part of the problem or the solution domain. In complex situations terms may be associated with a specific area of a problem domain. This property allows to group terms by their domains. Please note that the term should be unique within the project independent of its domain to avoid confusion. The name of the domain may link to a document that describes this domain (and maybe list all of its terms). This document may by itself be of type glossary item. You may also choose to use the Name List Macro to reference to these documents that describe the domain. |
| Section |
|---|
|
| Version Box |
|---|
| Since version 11.1 Domain has been removed and replaced by the relation. The relation existed prior to version 11.1 but did not provide its own doctype. |
Within a given domain terms may be related. This relation may be defined by a relation name. There is no explicit document type to define the relationThe name of the relation may link to a document that describes this relation (and maybe list all of its terms). You may also choose to use the Name List Macro to reference to these documents that describe the domain. |
| Section |
|---|
|
| Version Box |
|---|
| Since version 11.1 used to pick closely related terms. |
List terms with references to other closely related terms in this glossary items. |
|
| Section |
|---|
|
| Section |
|---|
level | 2 |
|---|
| Define the term within its domain. | Note Box |
|---|
While most document types use the description sections to inform the reader about what to expect from the document, the glossary item actually has the definition of the term as its description. Also note that this section does not demand a formal definition. So it is allowed to come as close as possible to define the term in the current context of the project (recognition rule). Projects sometimes need to define a working hypothesis for a term. Therefore it is also ok to just give a rough sketch defined by the team and the domain experts. For more information on this topic, please refer to Software Requirements & Specification by Michael A. Jackson. |
To describe a term define its scope and differentiate it by a span. The span constricts the applicability of the term within its domain and scope. While the domain is explicitly stated, the scope is not. The scope may be identical to the domain or some form of subdomain. |
| Section |
|---|
|
| Version Box |
|---|
| Removed to simplify the usage of glossary items. |
| | level | 2 |
|---|
title | SpecializationsSpecializations narrow the generalized definition by differentiation. This section lists subdocuments of this doctype. |
| Section |
|---|
level |
|---|
| 2 | title | List of Related Terms |
|---|
| | This section collects related terms by the relation Automatically lists items that are associated to this term. The terms are picked from the Related Terms property. |
| Section |
|---|
level |
|---|
| List translations of the term in other languages. These translations must not be used in the documents, but may help translators of technical documents. Usually you may add a two column table here, with the name of the locale (ISO 639 / ISO 3166 code) as the key and the translation of the term as a value. |
| Section |
|---|
level | 2 |
|---|
| List terms that mean the opposite of the defined term. This supports to relate the term to other terms in the domain. The table of antonyms is usually two columns: the key in the first column is the antonym term, the second column contains an optional note. |
| Section |
|---|
level |
|---|
| List terms that are different words for the same concept. Synonyms must not be used in the documentation to avoid confusion. The table of synonyms has usually two columns: the key in the first column is the synonym term, the second column contains an optional note that explains, why this term is not used. |
| Section |
|---|
level | 2 |
|---|
| Explain the differences to other terms that may be confused with the defined term. This supports to relate the term to other terms in the domain. Use a two-column table with the first column specifying the term and the second column explaining the differences to the defined term and notes. |
| Section |
|---|
| level | 2 |
|---|
| title | Deprecated Forms |
|---|
| List the forms of the word that have been deprecated. Add those words that have formerly been used for the term, but are now discouraged.List the deprecated term (first column) and the reason why it is deprecated (second column) in a table. |
| Section |
|---|
| Describe how the term is used in identifiers of programming languages (class names, method names, etc.) or other text files. This supports to name these constructs consistently throughout the project. The parts are only explicitly defined in the wiki, if they cannot be generated automatically. The rules may be checked by static analysersanalyzers. If such rules are applied, refer to them in the resource section of this document. |
| Transclusion |
|---|
| document | Document Sections |
|---|
| ids | standard-sections-bottom |
|---|
| |
|
| Section |
|---|
| | Section |
|---|
|
The page wizard demands the relation to group terms.
Image Removed
This is required to automatically fill the section with related terms. This could be annoying to have to define a relation group especially if the term should only be sketched. Just try to make your best guess and change it later, once the term is better understood. |
|
| Section |
|---|
| index | true |
|---|
| title | Related Doctypes |
|---|
|
|
...
| Section |
|---|
| index | true |
|---|
| title | Sub-Doctypes |
|---|
|
| Display Table |
|---|
| doctype | doctype |
|---|
| render-no-hits-as-blank | true |
|---|
| select | Name, Short Description |
|---|
| restrict-to-immediate-children | true |
|---|
| sort-by | Sort Key, Name |
|---|
|
|
| Piwik Set Multiple Custom Variables |
|---|
| Name | Value |
|---|
| Department | projectdoc | | Category | projectdoc-doctype | | Type | core |
|
