- Created by Robert Reiner, last modified on 16. Nov 2020
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 required changes 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. For these refactorings it is necessary to find all locations in the documentation that refer to the refactored content to check if these referencing locations also need to be altered.
In this topic we show which content 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 | 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 | 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 | 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 | A property control is metadata for a property. It controls how a property is perceived. A property control has a name and an optional value. | |
| 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 | 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 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 | 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 | 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.
Think of a dynamic link as the name of a variable in program code. If a software developer changes the name in one location, only the name at the given location is changed. If the developer wants to change the name of the variable in every location it is mentioned, then the refactoring tool "Rename a variable" is required.
An example for the use of dynamic links 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 to be documented and all values should link to the document that defines its semantics, then these documents may be added at any time. Later these documents may be removed. 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 instance to actually exist. This is especially powerful if these values are defined in a central repository.
Another form of dynamic link is provided by the Dynamic Document Link Macro. Here the title of a page is used to reference a document dependent on the space closure. See projectdoc Dynamic Link Titles for details.
Artificial Properties related to Naming
Since version 4.7 of the projectdoc Toolbox naming information is stored in form of artificial properties, named projectdoc Metadata Property.
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 list of document properties that can be used to query for documents that define a given name.
| Name | Short Description | Since |
|---|---|---|
| projectdoc IDs for Document Parts | Lists all used part identifier of a given projectdoc document. | 4.7 |
| projectdoc Macro Parameter Names | Lists the parameter names of all macros on a projectdoc document. | 4.7 |
| projectdoc Property Names | Lists the names of all properties, excluding projectdoc metadata properties, of a projectdoc document. | 4.7 |
| projectdoc Property Values | Lists the values of all properties, excluding projectdoc metadata properties, of a projectdoc document. | 4.7 |
| projectdoc Tags for Document Parts | Lists all used part identifier classes or tags of a given projectdoc document. | 4.7 |
Here is a list of document properties that can be used to query for documents that use a given name by reference.
| Name | Data Type | Short Description | Since |
|---|---|---|---|
| projectdoc Anchor IDs in Document Part References | Content Identifiers | Lists identifiers used by macros of a projectdoc document to identify anchored content on other documents. | 4.7 |
| projectdoc CSS Class References | CSS Classes | Lists all used CSS classes of a given projectdoc document that are mentioned as parameters of projectdoc macros. | 4.7 |
| projectdoc Display in Property Name References | Property Names | Lists the names of all properties that are referenced by a given projectdoc document via display property macros. | 4.7 |
| projectdoc Document Name References | Document Name | Lists the names of all documents that are referenced by a given projectdoc document. | 5.0 |
| projectdoc Dynamic Link Titles | Document Titles | Lists the titles of all pages targeted by dynamic links. | 4.10 |
| projectdoc IDs for Document Part References | Content Identifiers | Lists identifiers used by macros of a projectdoc document to identify content on other documents. | 4.7 |
| projectdoc Macro Parameter Name References | Macro Parameter Names | Lists the names of all macro parameters that are referenced by a given projectdoc document. | 4.7 |
| projectdoc Macro Parameter Name References in Remote Control | Macro Parameter Name | Lists macro parameter names used in the context of remote controls. | 4.7 |
| projectdoc Property Control Name References | Property Control Names | Lists the control names used by properties of a projectdoc document. | 4.7 |
| projectdoc Property Control Value References | Property Control Values | Lists the control values used by properties of a projectdoc document. | 4.7 |
| projectdoc Property Name References | Property Names | Lists the names of all properties that are referenced by a given projectdoc document. | 4.7 |
| projectdoc Select in Property Name References | Property Names | Lists the names of all properties that are referenced by Select parameters in a projectdoc document. | 4.7 |
| projectdoc Sort By in Property Name References | Property Names | Lists the names of all properties that are referenced by a given projectdoc document in Sort By parameters. | 4.7 |
| projectdoc Tags in Document Part References | Content Tags | Lists tags used by macros of a projectdoc document to identify content on other documents. | 4.7 |
| projectdoc Tokens in Document Part References | Strings | Lists identifiers and tags used by macros of a projectdoc document to identify content on other documents. | 4.7 |
| projectdoc Transclusion IDs in Document Part References | Content Identifiers | Lists identifiers used by macros of a projectdoc document to identify transcluded content on other documents. | 4.7 |
| projectdoc Transclusion Tags in Document Part References | Content Tags | Lists tags used by macros of a projectdoc document to identify transcluded content on other documents. | 4.7 |
| projectdoc Value References in Remote Control | Strings | Lists all values of remote controls that are not mapped to a property name by a macro parameter name. | 4.7 |
| projectdoc Where in Property Name References | Property Names | Lists the names of all properties that are referenced by Where parameters in a projectdoc document. | 4.7 |
Refactorings
Currently there are not many refactorings that are conducted automatically. A Confluence link, once the title of the referenced document is changed, will be automatically updated.
In all other cases, changing the name of a property, the name of a macro parameter, or the identifier or tag of a text content currently users need to find and update all referencing locations manually.
Here are some examples:
Changing a Property Name
In case the name of a property in the Document Properties Marker Macro is changed, users need to find all documents that refer to that name. The name may be uses in a Display Document Property Macro, in the Select, Where, or Sort By parameter of a Display Table Macro and many other locations.
The artificial property projectdoc Property Name References lists many of the locations that use a specific property.
There may be locations that are not reflected by the artificial properties. For instance the use of property names in user macros or in REST clients.
To query for documents using a given property name use the following constraint.
$<projectdoc Property Name References>=[My old Property Name]
Users need to open the documents in the result list of the query and adjust the property name accordingly.
Changing a matching Value
In this example the Where parameter of a Display Table Macro matches a property with a specified value.
$<Flags>=[Our old Value]
The artificial property projectdoc Property Control Value References lists the locations that use a specific value.
To query for documents using a given value use the following constraint.
$<projectdoc Property Value References>=[Our old Value]
Users need to open the documents in the result list of the query and adjust the property name accordingly.
Changing a Content Tag
In case a tag of a Content Marker Macro is altered, users need to find all documents from which this content is referred to. The projectdoc Tags in Document Part References of each document with such a reference contains this tag.
$<projectdoc Tags in Document Part References>=[my-old-tag]
Users need to open the documents in the result list of the query and adjust the tag name accordingly.
Changing a CSS Class
Users may have a new CSS class to render some tables that are currently rendered with a generic class. Some of the tables that use this class should use the new class.
To find the location where the generic table CSS class is used, use the following in your query.
$<projectdoc CSS Class References>=[our-generic-table]
Users need to open the documents in the result list of the query and adjust the CSS class name accordingly.
Tips working with Names
Here are a couple of tips for users of the projectdoc Toolbox when working with names.
Refer to Self by Placeholder
In case authors want to list documents that refer to the current document by some property should use the placeholder ${Name}.
For instance there is a Risk Severity doctype that needs to list all Change documents with a property named Severity with that value. The value of the Where parameter of the Display Table Macro would read:
$<Doctype>=[change] AND $<Risk>=[${Name}]
Some notes:
- For convenience the doctype constraint is typically specified by the Doctype parameter.
- In case the property named Risk is changed to Risk Severity or the name of the doctype change is altered to change-request, then the Documentation Architect needs to find all locations where the old names are used.
- More information on defining queries is found in Search Tips.
Use Name References in Queries
A Lucene search allows to specify the name of a property to match a given value.
Risk=high
To allow projectdoc to identify the left hand side of a constraint as a property name, it should be used like this:
$<Risk>=[high]
$<Risk>~(high, medium)
Only property names that are identified by $<...> or $[...] are recognized as property names. And only then are the values added to the artificial property named projectdoc Property Names and can be found with queries.
Reference Document Name by Transclusion
Transclusion macros allow to render the name of the document from which content is transcluded by the parameter Name as Heading.
Where the Transclude Documents Macro has no alternative approach, the Transclusion Macro may be wrapped inside a Section Macro and add a title manually. By using the Name as Heading parameter the rendered title will always be in sync with the document name.
Publishing Spaces
When working with multiple spaces publishing may be tricky if the publishing tool does not support publishing multiple spaces at once.
The projectdoc Toolbox allows to define delegate spaces for each space. The publishing spaces may define a coherent version of the spaces, while the publishing spaces define another delegate space. The names of the documents in the published and in the working space are the same. Only the space keys are different. In case a document with a dynamic link is copied, the link will automatically find the correct document identified by the name by looking up the space in which the document is stored. This approach requires that the names (in case of theName List Macro which works on names) or title (in case of the Dynamic Document Link Macro which works on titles) of the documents are unique.
Resources
More information on names and related topics.
- On Names
- A blog post on names. Names are essential since they provide scope and control the artifacts having a name.
- On Naming
- A blog post on how to find names and use them consistently in projects or products.
- Name
- Every document instance requires a name that should uniquely identify it within its doctype.
- Name and Title
- The purpose and the differences between the name and title property of a doctype.
