Documentation Development Process
Introduction
The key phrase to remember for documentation development is Customer Experience (CX). All documentation development, including associated processes, are meant to result in a great customer experience when readers are searching for, accessing, and using our documentation content.
In order to delivery such quality content, the processes described here and in related pages must be followed or exceptions must be granted by Technical Publications Production (Pubs Editors).
The development process for documentation normally occurs in synchronization with a project release/project life cycle and follows the DR (Decision Review), as it relates to the standard PLC and DR process. Here's a link a high level description of the documentation process available to all Genesys employees: Genesys Documentation Development Process.
Note: Individual writers should not send documentation directly to a customer or deliver documentation outside of the department for delivery to a customer unless prior approval has been received from Technical Publications Production department.
The Release Lifecycle consists of phases separated by Decision Reviews (DRs). A DR is the synchronization point between all stakeholders. At a DR, the results of the preceding phase and the conditions to proceed to the next phase are assessed, and the decision is made whether or not to approve successful completion of the preceding phase and to proceed to the next phase.
A DR ensures alignment with business strategy and portfolio product management process and requires management approval. Typically, all Release Level DR milestones are approved at the Executive level. For more details about the release management process, see Release Management Process.
Most projects move through DR0, DR1, DR2, and DR4. Products following a Continuous Delivery project type only use DR0 and DR4.
There are essentially three project types used at Genesys:
- Waterfall
- Agile. See guidelines for whole to manage writing on a Agile project.
- Continuous Delivery
Information Experience delivers various various types of content types. These types may be delivered online or in other format types, depending on when the product was released. This section provides a little information about these types.
Content Article
Content articles refer to self-contained units for information with a specific and limited purpose and our complete, in that they address the user's question. A content article follows a model where information is organized in a bottom-up architecture, reflecting the web environment, rather than the narrative book model.
Content articles cover areas that were previously covered in deployment guides, user's guides, reference guides, administrators guides, and so on.
These articles use the Every Page is Page One model developed by Mark Baker. Here are a few examples:
Release Notes
Release notes (RNs) provide information about new features, corrections, known issues, and other resources about a product component.
- For on-premises products, there's one release note is required for each component (IP). The RN is cumulative for each major release (X.Y.z), and is organized by the seven digit version number.
- For Genesys Engage cloud hosted, the RNs are still created by component but organized by release date. They may also include the 7-digit version number.
- For Genesys Engage cloud Private Edition, RNs are created for each service and also organized by release date.
Product Alerts/Release Advisories
Product Alerts (wiki) provide information about the product about which you want to alert the customer. For example, if your product requires a specific version of a component that's part of another product, that information could go in the alert. Previously, (Information that is specific to a component of the same product goes in the component's release note.) If you do not need to provide product-level information like this for your product, you do not need an alert.
Note: Previous to release 8.5, release advisories were in an html format. From 8.5 onward, Release Advisories renamed Product Alerts. They are online and added to same section of the product landing page as the Readme (https://docs.genesys.com/Documentation/Ponydocs/1.0/Help/readme). See the Management Framework product landing page as an example.
Wizard Advisories
Wizard Advisories provide information that the user needs to be aware of when using a product's wizard.
Deployment Procedures
A deployment procedure provides information to customers who are installing a Hot Fix patch for a component. If a deployment procedure is needed, only one deployment procedure covers each major releases (for example, Genesys Info Mart 8.1.x) with any specific hot fix information detailed in the release. (Prior to 8.0 each component hot fix had it own deployment procedure.)
For information on how to create a deployment procedure, see the Release Note Process, then select Detailed Release Note Development Process, and then Deployment Procedures.
Note: Some “Deployment Procedure” documents have been delivered in the past that are permanent documents and not installation for a hot fix. These documents are an exception to this process and will continue to be published like Release Notes.
Developer Documents
Developer Documents (sometimes known as SDK documents) are a distinct genre of technical documentation. They can include developers guide, API references, and code examples.
The recommended order for writing is to complete the API reference first, complete any code examples, and then complete the developer guide. Once written, developer documentation follows the same rules for review and delivery as other Genesys documentation. Review cycles are completed as indicated in the Technical Publications Freeze Form Process.
Code Examples
For Code Examples that accompany developer documentation, the associated writer can add these to the IX Repository folder for the product/version. (Note: Code snippets are provided inline.)
These rules apply to Code Examples:
- Files delivered by the writer are assumed to be technically correct.
- Technical approval of the developer guide implies technical approval of the code examples. Note: Each code example set must contain a disclaimer that these examples are not supported or tested.
- The code examples are zipped files in the .zip format for Windows and .tar.gz format for UNIX.
- The files are not checked or tested by Production Editing.
- These files must be listed as part of the documentation set for the product.
- The code examples are archived in Global IX SharePoint by the technical writer.
API Reference
Generally, the API Reference is the most used, and therefore most important, of the developer documentation set. In most cases, the API reference is an HTML tree generated from special comments in the source code for the product and shipped as part of the product. The HTML tree is not edited directly; edits must be made to the source code comments.
The technical writer:
- Does not submit an API reference HTML tree to the IX Production (aka Pubs Editors) group.
- Does not freeze it in XING.
- Does not archive the API reference HTML tree in ClearCase, as it is automatically archived when the developer archives the source code.
- Does verify with the Project Manager that the Packaging Specifications for the API reference correctly place it on the product CD.
- The API reference HTML tree is available from docs.genesys.com.
In the past and in some cases the API reference is a PDF file based on the FrameMaker templates following standard Technical Publications document development and submission procedures. It is also posted on the docs.genesys.com website. As with any other PDF, the technical writer archives the source files in ClearCase.
System-Level Guides
System Level Guides are documents that apply to general releases of most enterprise products, excluding versions that are restricted and some cloud products. System-Level Guides include:
- Genesys Supported Operating Environment Reference Guide (for on-premises products only)
- Genesys Interoperability Guide
- Genesys Support Media Interfaces Reference Manual
- Genesys Licensing Guide (Note: This document is outdated as much of the document is associated with License Reporting Manager (LRM) which is on the EOL track.
- DB Sizing Worksheets
- Genesys Migration Guide - this document is no longer maintained. Any instructions about how to upgrade to newer versions of a product are part of the product documentation, and may in fact be called a migration guide for the product.
- Genesys Hardware Sizing Guide
- Genesys Security Deployment Guide
- Genesys Resource Capacity Planning Guide
Help Files
These provide instructions how to use use a particular GUI application. Starting with the 8.5 release, Help Files are created online like any other document.
The individual writer or team lead plans documentation delivery according to the Technical Publications Development Process. A key delivery early on in the release cycle is product-level Customer Documentation Plan.
Details from the Documentation Plans are incorporated into other Genesys project deliverables including:
- (2021 notice -EPMS may no longer be used) The master schedule for the project in the Enterprise Project Management System (EPMS). Writers should check with their Project Managers to determine how to deliver the documentation schedule so that it is accessible to the entire team. In most cases, only the Project Manager will make changes to the project schedule, and he/she will add the documentation dates as provided by the writer.
- (As of 2021, the Packaging Spec is online and only lists RNs.) The product Packaging Specifications, which serves as the baseline for work performed by the Project Support Office and Production in preparation for releases. For example, from the Packaging Specifications, the names of documents and the titles of Release Notes are loaded into the XING, JIRA, and the Production databases. The Packaging Specifications are the official record of manuals, help files, online (wiki) docs, code examples, release notes, advisories, and any other types of documentation deliverables for an individual release of a product. It is imperative that the writer work with the Project Manager to ensure that the Packaging Specifications contains a correct list of Documentation Deliverables. The Project Manager will also submit the Packaging Specifications for review to the PCT and must receive approval from the Technical Publications Lead on the PCT.
Note: The official policy of the IX department is to discourage custom documentation for individual clients; however, the department follows normal processes to develop required documentation for custom projects that are a part of the Engineering Plan of Record.
The links below are to pages that provide information on what Tech Pubs members do from DR0 through post-DR4 for Waterfall projects.
- DR0 to DR1
- DR1 to DR2
- DR2 to TR
- TR to DR4
- Post-DR4