- Created by Robert Reiner, last modified on 23. Jul 2020
You are viewing an old version of this page. View the current version.
Compare with Current View Page History
« Previous Version 3 Next »
projectdoc Toolbox
Overview over tools in the projectdoc Toolbox that support authors and information architects to rename elements of their technical communication or documentation.
When working on projects or products teams continue to learn. It is important to reflect what has been learned in 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 there views on the domain and reflect this in their artifacts, their solutions would probably be more complex than necessary. The code not 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. Move documents to other spaces and the like.
In this topic we show which elements of the projectdoc domain have names and show tools that allow to locate the documents in which these names are used. This introduces to means of refactoring 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 refering 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, it does not require a value. Once added authors may reference the property within a given 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 a 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
Most of the defined names can be referenced by macro parameters.
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 identifier.
Macro instances and macro parameters are referenced by macros supporting Remote Control.
Names that can not be referenced by macros, at least currently, are property controls, macros and CSS classes.
Documents using Names
A typical refactoring task to rename an element requires to locate all location where this name is currently used.
Since version 4.7 of the projectdoc Toolbox this information is stored in form of artificial properties.
- No labels
