Available translations

Definition Pages

foundations.png
Summary: A definition page, also known as Docs Node Page, is the page that describes what a node is or represents in any given hierarchy, how it works, and how it interacts with other nodes. It's the page users access when clicking the help (?) button on a node's menu.
This page is the main source of information about the particular node. Think of definition pages as the place where people should find all the details about the behavior of the node, including its configuration.
Foundations->Topic->Docs Node Page->Content
A Docs Node Page features:
  • Definition: a short description of what the node is, and what it represents in the hierarchy. The definition is displayed to the left of the node's icon.
  • Content: all the information relative to the node in terms of how the node is used, how it affects operations, or how it relates to other nodes.
  • Configuration: a section describing the elements of the node's configuration file.
  • Auto-generated content: information extracted from the system, workspace, etc., to provide the technical context in which the node exists.
Definition Box
The definition box is the top paragraph on a definition page, rendered to the right of the icon representing the node, in bold.
Use this space to write a concise, accurate, and careful description of WHAT the node is or represents. As part of this definition, you may include WHAT the node is used for, as it is the use of the node that determines what it is or represents in the first place.
Do not include any other type of information in the definition box. Do not explain how to use the node, how the system uses the node, or how the node interacts with other nodes. The definition box must answer the WHAT question, and nothing else.
Using Blocks and Includes
The rest of the definition page is organized in blocks.
We build pages using blocks so that we may later include blocks of content on other pages. This concept of blocks and includes is crucial to avoid duplicating content. When writing a Topic page, you will many times want to refer to content that exists on another page. If that piece of content is set up as a block, then you may include it.
And this is the perfect example! I need to explain how to create blocks, but instead of writing the whole thing, I will include content from the Docs Block Style page.
Foundations->Topic->Docs Block Style->Definition
docs-block-style.png
Use block paragraphs to define blocks of content with any number of paragraphs. A block starts with the paragraph that is assigned the Docs Block Style and ends on the last paragraph before the next paragraph with a Docs Block Style, or where the page ends.
Foundations->Topic->Docs Block Style->Content
To start a new block, write the name of the block in a new paragraph and apply the Docs Block Style.
Once you apply the Docs Block Style, the paragraph seems to disappear. It doesn't though. What happens is that the paragraph gets assigned a CSS style that makes invisible the name you wrote, and displays a faint triangle pointing downwards that is highlighted upon mouseover. The triangle now marks the start of the block.
To end a block, create a new block after it. If you don't, then the block ends wherever the page ends.
Content Block
All definition pages must have a Content block. In fact, the first paragraph on the page must be the block definition.
Let's try with an example right here!
Content
The content block is where you explain HOW the node works. This is where you explain how the system uses the node, how the node interacts with other nodes, and how users may use the node.
Configuring Block
This block may or not be required, depending on the node. If the node has a configuration, then we use the Configuring block to explain each property.
Take a look at the LAN Network Node page for an example.
Notice that after the definition of the block, we write the title of the section as follows:
 Node Type + Configuration
Following the earlier example, that would be:
 LAN Network Node Configuration
We use a title to separate the two sections or blocks on the page, pretty much in the same way we use titles elsewhere. Notice that the title must be inside the Configuring block so that the title is included as well if we ever wish to include this block on another page.
Also notice that we don't use a title after the definition of the Content block. It is simply unnecessary, and the page reads better without one.
Auto-generated Information
Wherever the content you write ends, the system includes several automatically-generated sections. Take a look at this type of content just so that you notice that you don't need to manually include in your writeups any of the details the system generates automatically.
Previous
Documenting New Projects
Next
Iterating on Definitions