Authoring - Overview

Structured authoring is a method of writing and arranging content that relies on rules and a way to enforce these rules. It also separates structure from content and presentation. Structured authoring improves the management of information by creating a consistent content structure that is used throughout a document or a project. This structure helps in the creation of small topics  which are stored as reusable objects.

In HelpServer, you achieve this by defining content architectures and documentation standards by the use of classes. Once defined, these classes guide content through the development process. This approach may seem restrictive at first, but it saves time in the end by forcing documentation to be complete, consistent, and designed for re-purposing.

With HelpServer you work with folders and topics. Folders are the containers to hold other objects in a structured manner. Topics hold the actual content, which is text, images, video, sound, etc. To keep the content well organized, there are several kinds of folders and topics. Examples of folder kinds are ‘Library’, ‘Book’, ‘Chapter’, ‘FAQ’. Examples of topic kinds are ‘Topic’, ‘FAQ topic’, ‘Glossary term’, ‘Window help topic’, and ‘Field help topic’.

Each kind of folder or topic has its own behavior: a book consists of chapters, and chapters consist of other chapters and/or topics. A library holds books. Is a library also meant to directly hold topics? Try adding a library folder to our ‘Animals information’ folder and popup its menu as demonstrated in the figure below.

A library’s allowed objects

You won’t be able to add topics directly in the library folder because a HelpServer ‘Library’ is set up only to contain folders of the kind ‘Book’ and/or ‘Bookshelf’. ‘Chapters’ or ‘Topics’ are more likely to be added in a ‘Book’ and/or another ‘Chapter’.

Here, we will use the term ‘class’ rather than ‘kind of ’. From now on, we’ll talk about ‘folder classes’ and ‘topic classes’.

Thus, with classes you define an allowable structure for your content. Because you can enforce structure rules, the authors will have more control over their workflow. While creating content, authors are guided through the available classes of folders and topics. This prevents them from making a mess of the structures of the content. For example, they cannot add or paste a ‘Book’ under a ‘Chapter’. If an author wants to create a new book, he has to do this in a ‘Library’ or ‘Bookshelf’ folder.

The setup of the default classes can be changed. However, a better approach would be to define your own classes and not to change the operation of HelpServer’s default classes too much. Setting up folder and topic classes is a challenging task that requires additional up-front planning. When to define your own classes is up to your organization or documentation project:

 

The guidance that structured authoring provides to authors is more important in large organizations and large documentation projects.

 
 

For small-scale help and documentation projects, you would probably be better off using the default classes.

 
 
X

Something that is mentioned a lot is the importance of separating structure from content. Understanding the difference between structure and content can be difficult at first, especially if you're used to not thinking about the semantic structure of a document.

In HelpServer's Workbench you do not work with the actual content objects. Instead, all content objects (folders, topics, etc) you see in the Workbench are in fact references (i.e. links) to content objects. You can compare these references with the shortcuts in Windows Explorer. However, in Windows Explorer you have also access to the actual content objects (the files and the folders) while in the HelpServer Workbench the actual content objects are hidden and are only manipulated by the system.

This approach allows a full separation of structure and content and it makes reusing an object just a matter of copying and pasting. In this sense, you are not just separating things in one place, you are bringing them together in another.

 
X

HelpServer fully separates the presentation from the content by means of page styles. This kind of separation enables you to factor out repetition and shared aspects and deal with them only once. In this way, managing the presentation of a document becomes much easier, and the same document can be presented in several ways.

HelpServer's page styles are very flexible, require no scripting or programming skills, and meet the requirements of most help and documentation projects. You can easily determine the way in which navigation bars, action bars, and the body of all the web pages are laid out and presented to the user in the browser window. You can define colors, fonts, icons, and buttons and even add sound effects and animation.

 
X

Is the accuracy of your content in question because information about the same subject appears in multiple systems and in multiple formats across your company?

Is the problem of duplicated information an ongoing challenge for your organization?

HelpServer helps you improve data accuracy by consolidating all content into a single, reliable source, and also manages the web of relationships that exists between disparate content objects.

By means of a copy/paste or a drag/drop operation, you can reuse a content object in several assets without losing visibility of the impact of changing it. This prevents redundancy and updates to reused content cascade everywhere, ensuring content accuracy for all your deliverables. Thus, you and your co-authors can easily reuse content throughout your entire organization in future documents.

Authoring

 About HelpServer
 Starting up and logging on
 The basic working principles
 Using the content in help and documentation systems
 Formatting the content
 Searching and replacing text
 Reusing content with shares
 Navigating with hyperlinks
 Navigating with pointerpaths
 Using bookmarks and jumps
 Duplicating content with clones
 Using tables
 Including media files
 Navigating to web pages
 Using embedded chunks
 Including html code
 Navigating with menus
 Using snippets
 Spelling checking
 Using the view mode
 Creating an index
 Creating a FAQ
 Creating a glossary
 Team authoring
 Working with projects
 Setting up structured authoring
 Overview
 Setting up folder classes and topic classes
 Creating the project
 Changing the class behavior
 Extending the class structure
 Using chunks
 Searching for object classes
 Generating file based output
 Creating printed output
 Importing files and folders
 Loading files in the project gallery
 Converting legacy content
 Including legacy content in real time
 Transferring objects between installations
 Smartcontent
 Notification
 Feedback
 Translating
 Customizing the look and feel
 User accounts
 Security
 Working with templates
 Working with metadata
 Versioning
 Auditing
 Workflow management
 Annotations
 Using event exits
 Appendix A: The URL parameters
 Appendix B: The object indicators
 Appendix C: Play Javascript