- Created by Robert Reiner, last modified on 25. Jul 2020
You are viewing an old version of this page. View the current version.
Compare with Current View Page History
« Previous Version 6 Next »
projectdoc Toolbox
A short overview over tools in the projectdoc Toolbox that support authors and information architects to rename elements of their technical documentation.
When working on projects or products, teams continue to learn. It is important to reflect what has been learned in the naming and structure of the produced artifacts.
When software developers understand a concept of the problem domain better, they immediately need to alter their model or maybe just their vocabulary to reflect this better understanding. If they would not alter their views on the domain and reflect this in their artifacts, their solutions would probably be more complex than necessary. The code would not be as easy to understand as it could be.
The same is true for any form of documentation. In case a term or name is not accurate for the referred thing, it probably will evoke an inaccurate understanding of the thing.
These changes that are based on the understanding may require refactorings or reengineering. A refactoring is a change that will not alter the external observable behavior. In software development projects changing names of types or methods is a refactoring. In case a change alters the way of processing that will alter the generated output, we speak of reengineering.
In the domain of technical communication, we also refer to changing the name of a document, a property, or the title of a section as refactoring. We may want to extract blocks of a document and move it to its own referenceable document. Or move documents to another space.
In this topic we show which elements of the projectdoc domain have names and introduce tools that allow to locate the documents in which these names are used. This article explains refactorings with the projectdoc Toolbox, focusing on naming.
Named Elements
The projectdoc Toolbox uses names to identify elements of the technical communication domain. Some names are referring to a unique element, other names refer to a collection of elements. Looking at names in this domains reveals two contexts of using names:
- Context where a name is defined
- Context where a name is referenced
Definition of a Name
A name is defined by naming an element of the technical communication. Creating a projectdoc document requires the author to provide a name for that document. Once created other authors can refer to the document by this name. The same is true when adding a property to a document. The property requires a name, and optionally a value. Once added authors may reference the property within a given document by that property name.
Here is a list of elements that can be named within the domain of the projectdoc Toolbox.
Element | Designator of Name | Description |
---|---|---|
Unique Document | Document Title | In Confluence this is the title of a page which is also the title of a projectdoc document. The title of a document is unique within a single space. |
Document | Document Name | The name of a document is often identical to the title of the document. But they may be different in case two documents within a space require to have the same name. For instance there could be a resource document for a website with the title "Domain Driven Design" and there may be an entry in a glossary in the same space that has also the name "Domain Driven Design". |
Property | Property Name | Each document has a set of properties. Some properties are first class citizens in the domain, other properties are metadata. Some properties are derived from the context and are called artificial properties. Each property has a name and an optional value. It may also have metadata in form of property controls. |
Property Control | Property Control Name | A property control is metadata for a property. It controls how a property is perceived. |
Section | Section Title | The title of a section identifies a section within a document. The title of a section is not required to be unique. Multiple sections within a single document may share the same title. |
Unique content | Content Identifier | A unique content, which may be a section or a smaller block of content within a document may be identified uniquely within a document. Technical the content has an HTML identifier. An identifier of an HTML element is required to be unique. Therefore sections with such an identifier that share the same title show a suffix in their identifiers, such as |
Content | Content Tag | Content may be tagged by names shared by many contents on the same document. The content tag is defined within macros and may be referenced by other macros. A typical use case is transclusion. Authors tag a couple of sections with a content tag and refer to that tag by the transclusion macro. The transclusion will render all content tagged with the specified content tags. |
Macro | Macro Identifier | Macros are identified by their name. All macro instances share that name. For instance, the name of the Content Marker Macro is |
Macro Parameter | Parameter Name | Macros are configured by parameters. A parameter has a mandatory name and a value. The name of the parameter is defined by the author of the macro. |
Macro Instance | Macro Instance Identifier | A macro instance is a macro on a document. There may be macro instances of the same macro on a single page. For instance a document typically has multiple sections. Each section is rendered by a Section Macro. Hence there are multiple macros by the name |
CSS Class | CSS Selector Name | A CSS class is a name that references a set of styles that are applied to an element on a document. The CSS class is defined in a stylesheet. The name of the set of styles can be referenced by a selector. Some macros allow to add names of CSS classes to apply a set of styles. |
Referencing a Name
By referencing a named element something needs to be applied to that element or information is fetched from that element.
Most of the defined names can be referenced by macro parameters. Some names, like CSS classes are simply matched by CSS selectors to apply styles. Other names cannot, at least currently, be referenced like property controls or macro names. These names are used internally to control the way processes are executed.
Here are some examples.
- The Display Document Property Macro allows to reference a property by its name within a document referenced by its title. The Name List Macro allows to reference a document by its name.
- Sections can be referenced by the Transclusion Macro or Transclude Documents Macro by its section title, unique content identifier, or content classes.
- Macro instances and macro parameters are referenced by macros supporting Remote Control.
Working with Names
When a name references an element, such as a document, there is a link between the location where the name is mentioned and the document with that name.
When the referencing name is altered, it may be of two reasons.
- The location refers to the wrong element. The name is changed to a name that refers to the right element and the issue is resolved. The names of the elements need not to be changed.
- The name of the element is wrong. Now it may be that the referencing location refer to the correct element, in which case the reference name needs to be adjusted accordingly. Or the reference has the correct name, but the element with that name does not exist.
The projectdoc Toolbox provides two concepts to deal with the use cases of reason number 2.
Static Links
The Display Document Property Macro and its cousins are static links. They point to an element and in case the referenced elements is renamed, the reference is also altered.
For instance a minutes document refers to a participant named Janc Doe. If someone identifies Janc as a misspelling of Jane, the reference in the minutes document still holds.
Another example is the renaming of the concept of an Architecture Aspect to a Crosscutting Concern. The references are correct, but the name with which the element is referenced need to be changed.
Static links may have a different label. If a Confluence link refers to a Confluence page, the label of the link and the title of the page match. The label may be different, for instance the label team members may reference a page with title Team Member. When the title is changed, the label will not, although the link still refers to the same page.
Dynamic Links
The Name List Macro and its cousins are dynamic links. They define a property value and it is assumed that this value is correct. If there is an element that is identified by that name, a link is rendered. So the main aspect here is that a property name is associated with a value. The link is optional.
An example is a risk severity of high, medium, and low. The property value for a document may be set to any one of these values. If the documentation architect decides that each of these values requires a document and all values should link to that document, then these documents may be added (or removed) at any time. The values for the property in each document are not altered by any of these actions.
The power of dynamic links is that elements can be virtually referenced. A reference can be added, e.g. by a Template Author, without the need of the referenced document to exist. This is especially powerful if these values are defined in a central repository.
Artificial Properties related to Naming
Since version 4.7 of the projectdoc Toolbox naming information is stored in form of artificial properties.
This information is especially useful for refactoring tasks. To rename an element typically requires to locate all location where this name is currently used. Then the author can decide, which name references must also be altered.
Here is a lost of document properties that can be used to query for documents that use a given name.
The query matched no documents.
- No labels