About Structured Authoring
Structured authoring is an XML-based approach to technical documentation that simplifies consistency, content reuse, and team collaboration. Pre-defined rules in a DTD or Schema controls the content and structure.
Paligo is a structured authoring tool, which uses a topic-based customization of the DocBook 5.1 XML standard. If you are completely new to structured authoring and topic-based authoring, the following sections are recommended to in order to grasp some basic concepts that will help you get the most out of Paligo.
Structured authoring is a standardized approach to writing technical documentation where the content is controlled by pre-defined rules. The technical writer is not concerned with styling or formatting, but instead marks up the content according to what it semantically represents.
Structured authoring is defined by the following characteristics:
-
The structured content is usually based on XML.
-
The content and structure are controlled by rules. These rules are enforced in software using a DTD or Schema. Such rules can specify that a
sectionmust contain atitle, aproceduremust containsteps, and so on. -
The structured content is tagged/categorized using semantic tags that reflect what kind of content it represents rather than how it should be styled.
If you write a an instruction, for example, it can be represented by the very appropriate semantic tag
procedurerather than a simple numbered list, and so on. -
In structured authoring, content and layout/formatting are separated. The technical writer is not concerned with formatting, which is applied separately using stylesheets (XSLT and CSS).
-
The structure and semantic tagging enables and simplifies content reuse, increasing both consistency and efficiency in technical documentation.
-
Structured authoring also enables and simplifies the automation of publishing technical content and applying formatting separately and dynamically.
-
The structure is hierarchical/nested in nature. So, for example, a
figureelement can represent a unified block of content that can hold a title, an image, and a caption (etc) as child content. -
Structured authoring also simplifies team collaboration, and the consistency it provides is a prerequisite for robust component content management.
In Paligo, you will create structured content. This is content that contains structural elements as well as the text, images, etc., that your readers will see. The structure helps to make sure that the underlying code of your content is consistent, so that it is easier to control, manage and convert into different formats. It is also easier for other systems to process.
Structured content is written in XML, but you do not need to understand XML in great detail. Paligo hides much of the code in the background and provides user-friendly tools that make it easy to write structured content. However, you will find it easier if you understand the basic principles:
-
You write content in topics and organize them in publications. When you publish, the content is converted into an output format, such as HTML, HTM5, or PDF.
-
To create content, you need to add elements for the structure and then add your text, images, etc., inside the elements. You can think of elements as "building blocks" that define the type of content you are adding.
-
There are rules that govern where each element can be used. You do not need to know the rules as Paligo will guide you.
Everybody who writes in Paligo uses the same set of elements and so follows the same rules. So you can have lots of different writers working on your projects and they will all produce content that has the same underlying structure.
-
Content and styling are separate. Your topics only contain structure and content. The Paligo content model has semantic elements that describe what the element is for, like a procedure is intended for procedures/instructions.
By utilizing the semantically tagged content, the styling can then be applied to the content separately, and this means you can apply different styling to the same content in different outputs.
-
You can reuse topics, groups of elements, or individual elements.
This can save you a lot of time when creating and updating your documentation. The idea with content reuse is that you write content once, in one place, and then reuse that content wherever it is needed. When you need to update your content, you make the change once and it applies wherever that topic or element is used.
-
You can move entire blocks of content or individual elements, depending on your requirements.
To find out more, see Move Content.
The following image shows how a simple piece of structured content appears in the Paligo editor.
The underlying code (XML) of this content is shown below. You can see that there are elements that define the structure and each element indicates the type of information. For example, title is for the heading, procedure is for the procedure,
and for each step there is a step element and para element to contain the text in the step. The section element is a container for the other elements. Every topic has a section element and the other elements have to be inside the section.
<section> <title>Using Elements</title> <para>This paragraph uses a para element.</para> <para>This paragraph also uses a para element.</para> <procedure> <step><para>This is a step element inside a procedure element.</para></step> <step><para>This is also a step element inside a procedure element.</para></step> </procedure> </section>
When you create content in Paligo, it is important that you understand that the content is structured. There are elements for different types of content, and these are organized into structures. For example, if you add a note to a topic, it has this structure:
<note>
<para>Text of note.</para>
</note>
Here, the note is the "parent" structure and the para is the "child" structure, as the para is inside the note (it comes after the opening <note> and before the closing </note>.
When working with content inside a topic, the parent-child relationship is important. Any time you move, copy, or delete a parent element, then that action also applies to the "child" elements inside it. So, using the simple note example again, if you copied the note element, Paligo would create a copy of the note element and also a copy of the para element inside it.
Note
When you copy, move, or delete a "parent" element, the same action applies to its "children".
If you copy, move, or delete a "child", the same action only applies to the "child" (and any of its children). The action does not apply to the parent.
This hierarchical "parent-child" structure has some useful advantages for technical writers—it means you can move, copy, and delete entire structures at once, rather than having to manage them separately. It is especially useful with more complex structures, such as lists, as it can make it much easier to change the list order, move content, etc. The following example shows the parent-child relationships in a procedure.
Tip
If you are unsure about the hierarchy of elements and how the parent-child relationships work, create a test topic and experiment with it. We recommend that you add a mix of regular paragraphs and more complex structures like lists and tables and then try copying, moving, and deleting the parent and child elements.
For example, let's look at a more complex structure, such as a procedure. (This image is taken from the XML Tree View, which is available in the side panel of the main editor. It shows the structure of the topic you are working on).
Here, we can see that the top-level element in the topic is the section. Every topic has a section element at the top, and these are the main "container" in the topic. If you had a topic with subsections, you could have lower-level sections too (although it is often preferable to insert these as components rather than as sections).
Inside the section, we have all of the other elements. These too are arranged in a hierarchy. Title is a second-level element and it does not have any other elements inside it (so has no "children"). Procedure is also a second-level element. It has a plus icon + to show that it is expandable and has elements inside it (its "children").
Inside the procedure, there are two steps. The steps are "children" of the procedure.
Inside the first step, there is a para. This is a "child" of the step and a "grandchild" of the procedure.
Inside the second step, there is a para and a note. These are "children" of the second step.
The note also has a para inside it. The note is a "parent" to this para, and the para is a child of the note, a grandchild of the second step, and a great-grandchild of the procedure.
When you work with content inside a topic, it is important that you understand that there are parent-child relationships between the different elements. Because when you move, copy, or delete an element, the action applies to its children too.
So if you select the second step and move it above the first, Paligo will:
-
Move the second step above the first step in the procedure
-
Move all of the descendants of the second step (children, grandchildren, etc.) as well.
This means you can quickly and easily move, copy, and delete multiple elements or individual elements with a single action.
Paligo is designed for "topic-based authoring", which is a more efficient way of producing and managing documentation. If you are new to topic-based authoring, this section explains the basic principles.
With topic-based authoring, you create each section of your content in separate "containers" called topics. So instead of creating your entire document in one place, as you would in a Microsoft Word file, you create lots of separate topics. As a general rule, you should create a topic for each section of your content that needs a heading.
For example, the following page has two sections with headings, so to create that content in Paligo, you could add one topic for section 1 and another topic for subsection 2.
 |
1 = Section, 2 = Subsection
Writing content in topics has many benefits. They are easier to manage and translate, and you can reuse them in different publications. This can significantly reduce the cost of updating your content, as when you change a topic, the changes apply wherever that topic is used.
Note
If you have each section and subsection as separate topics, they are easier to reuse in different contexts. But there are ways to add sections and subsections in the same topic. To find out more see Headings and Subheadings.
Tip
You can easily make a separate topic of a subsection, by selecting the section in the Element Structure Menu and choosing the option Convert to reusable component.
 |
A Publication represents a collection of topics that you want to publish as an output, such as an HTML5 help center. Think of them as a table of contents, where you choose what topics to include and what order to present them in.
The following image shows a publication for a "Mars Travel Manual". You can see that the publication's structure looks like a table of contents and it has various sections. Each of those sections is a separate topic (so there is a topic for "About Space Travel", a topic for "Space Safety", a topic for "The Mission Control Center" and so on).
 |
A publication called "Mars Travel Manual" which contains many topics, including "About Space Travel", "Space Safety", and "The Mission Control Center".
You can add a topic to more than one publication. This is one of the main benefits of topic-based authoring, as it means you can write a topic once, and then use that same topic in many publications.
 |
A topic can be added to many publications.
You can also publish part of a publication rather than the entire publication. This is useful if you have sections of a publication that could work as a separate output.
To learn how to create publications and topics, see: Create a Topic and Publications.
When you write in Paligo, you will use elements to create the structure in your topics and add meaning to selected parts of your content.
Elements are tags that contain your content, and there are many different types of element that you can use, for example, there is a para element for paragraphs and a procedure element for process lists. Paligo uses a customization of the
DocBook 5.1 XML standard and you can use any element included in that standard.
The elements that you use to build the structure are "block elements". There are also "inline elements" which you can use to mark up content inside a block element.
Note
To find out about the elements you can use, see Common General Elements and Basic Element Reference.
In a topic, you will add block elements to define the structure, and then you can add your content inside the elements. Think of the block elements as "building blocks" that represent different types of information.
The following images show how block elements form the flow and structure of a topic. The first image shows how the topic looks in the Paligo editor. The second image shows the underlying code of the topic, and we have color-coded the elements to show you the block structure (for illustration purposes only).
There is a block element for each different type of content and the elements are arranged in a hierarchy. For example, the procedure tag contains all of the steps in the procedure list, and for each step, there is a para element for the paragraph text.
There are rules about where you can add each element, and this is how Paligo makes sure your content has a consistent structure. You do not need to know the rules as Paligo will advise you if you add an element in an invalid position.
Tip
To learn how to add block elements to a topic, see Add Content to Topics.
Inline elements allow you to add meaning to content that is inside a block element. For example, if you are writing about software, you might want to use the guilabel inline element on the names of user interface options in your text. Another common example of an inline
element is the emphasis element, which you can use to italicize one or more words.
There are many different inline elements available for use. We recommend that you look at the full list and identify the ones that are most useful for your content and then agree to use them consistently. You do not have to use them all.
To view a list of the inline elements, select a position inside a para element. Then use the element context menu to display a list of all the inline elements that are valid at the selected position.
 |
Note
To access the element context menu, press Alt and Enter (Windows) or Option ⌥ and Enter (Mac).
Tip
For information about the purpose of each element, refer to the DocBook documentation.
To learn how to add inline elements to a topic, see Add Content to Topics.
Every element has a set of attributes, which are properties that define the element's characteristics. For each attribute, there is a value, and by changing the value, you can control how Paligo uses the element.
Some common examples of how you can use the element attributes are:
-
Set the
widthattribute of animageobjectto control its size in the output, for example, width: 50% -
Set the
roleattribute of asectiontoaccordionso that the section appears as a collapsible section in the output -
Set the
audienceattribute ofparatodeveloperso that the paragraph only appears in content aimed at developers.
You can see an element's attributes by selecting the element and then looking at the Element attributes panel in the Editor:
The Element attributes panel shows the attribute values that are currently applied to the element (1).
You can add extra attributes from the Add attribute drop-down menu (2). If you add an attribute, you need to set its value in the field next to the attribute name in the Element attributes widget (1). You can also use the fields to change any existing attribute values.
To find out more, see Add Element Attributes.
There are many different element attributes available, see Basic Element Reference.