User roles and timelines

Administrators configure roles and timelines to help DITA CMS documentation team members manage the documentation cycle.

Roles define the responsibilities of various members of the documentation development team. Each part of a documentation project—topics, maps, images, and resources—has its own set of users who work on it at different points in its development. The DITA CMS keeps track of the user roles and their relationship to each other and to the document's status, as the document moves through its life cycle.

User responsibilities

To illustrate the concept of roles, let’s say that an organization identifies three user roles with regard to topics: Author, Reviewer, and Editor. In a typical project scenario, an Author writes a topic and sends it to the Reviewer to be appraised. If the Reviewer requests changes, the topic goes back to the Author to be reworked and may be yet again submitted to the Reviewer for approval. The topic might then be passed to an Editor for proofreading and then finally re-submitted to the Author for publication. Roles vary from organization to organization. Larger companies typically have more roles and more stages in the documentation process, while in small companies one person may fill several roles.

Timelines

Timelines correspond to the degree of involvement that a user role has at any given point in the document life cycle, as shown in the table below. There are five main timeline states:
  • Active: Tasks will be active for this user role at this point in the document cycle.
  • Incoming: Tasks are pending for this user role at this point in the document cycle.
  • Retained: Tasks will be passed back to this user once another user has finished them.
  • Done: The user has completed the work on this document.
  • Out of scope: The document is out of scope for this user role.

For example, when a writer is working on a document, the document is active for this user, but incoming for reviewers and editors. When the writer hands over the document to a reviewer, the document is retained for the writer (since there might be more work to be done by the writer on this document after the review, so the writer retains a certain amount of responsibility), active for the reviewer, and incoming for the editor.

Topic status Timelines
  Author Reviewer Editor
Authoring:work Active Incoming Incoming
Authoring:content/review Retained Active Incoming
Authoring:edit/review Out of scope Out of scope Active
Authoring:done Done Done Done

Status and email notifications

Each time a document's timeline status changes, it triggers events in the system that keep users alerted to document status as it affects their own role in the documentation process. For example, the DITA CMS can be used to send an email notification to users any time a document becomes Active for their particular role. Users can view the documents they have been assigned and their timelines in the Todo List tab within the DITA CMS workspace.