As discussed in Page Name Management and Name History and Page and Comment Moderation, TeamPage provides a powerful set of tools for creating wiki-style online documentation. Page and comment moderation can also be used independently from using named pages. This article provides hints and techniques that will help users more effectively use these capabilities.
Using Read Published, Read Draft, Author, Edit and Publish Permissions
By assigning Read Published Articles, Read Draft Articles, Author, Edit Articles, Publish Articles, etc. permissions to various accounts, in combination with use of various project settings, you can support a variety of documentation access and workflow requirements. For example, you can create the following conditions:
Selected users only see published content
In this case, you would not give these accounts Read Draft Articles, Author, Edit Articles or Publish Articles permissions, only Read Published Articles permissions. (If making the documentation project accessible without using a login account, this would apply to the Visitor account.) Since the users do not have Read Draft Articles permissions, they will only see the published versions of pages, even when draft versions exist. They will also be able to see and click on links to:
1) pages for which only a draft version exists, in which case they will receive a message that a draft version exists, but they do not have the rights required to view it
2) pages for which the name has been created, but the page does not yet exist, in which case they will receive a message that the page does not exist and they do not have the rights needed to create it
Only selected users can publish content
In this case, you give Publish Articles permissions only to the "publisher/editor" accounts and not to the accounts of users tasked with creating draft versions. Thus, you will have:
1) Authors, with both Author and Read Draft Articles permissions. Depending on workflow, these accounts will at least have Edit Own Articles permissions and frequently have Edit Articles permissions.
2) Publishers, with both Read Draft Articles and Publish Articles permissions. Depending on workflow, these accounts may also have Edit Articles and Author permissions.
3) Publishers, or a subset of this group, can be given Lock/Unlock Articles permissions so they can prevent or allow the creation of a new draft version of an article.
This scenario can be further refined by using the project setting that determines whether an account with Publish Articles permissions has the Article Editor set to publish articles by default when they are posted.
Using Moderation Projects
When comments are posted directly in a documentation project, Traction will automatically manage the visibility of comments made on draft articles. These comments will be visible only to accounts with Read Draft permissions as long as the article they are commenting on has not been published. However, as soon as the article is published, these comments will become visible to all accounts with Read permissions for the documentation project. Likewise, comments made on articles that are in a published state will be visible to accounts with Read permissions.
Therefore, in the case of a documentation project which is intended for readers who should only see published pages, it is frequently useful to use a Moderation Project as the project where comments on articles/pages in the documentation project are posted. The main advantage of using a Moderation Project is that the visibility of the comments posted to it will then be tied to the Read permissions granted for that project, rather than the Read permissions for the documentation project itself. When using a Moderation Project, the project administrator for the documentation project can require that all comments on the documentation project be posted only to the designated Moderation Project or that the Moderation Project be the default project for comments, but users can choose to post comments to any other project where they have Author permissions.
When using a Moderation Project, it may also be useful to:
1) Apply labels from the Moderation Project to articles and individual paragraphs in the documentation project, so that they are not visible to accounts that do not have Read permissions for the Moderation Project. See Using Labels to Help Manage Updates below for some ways you might want to use labels in conjunction with moderated publishing.
2) Locate sections for managing moderated publishing and named pages in the Moderation Project, rather than in the documentation project itself.
Tip: It is also possible to have users post their comments on pages in a documentation project to projects that only their team/company has Read permissions for. This essentially creates "private" comments that only members of that team/company see when looking at the documentation project.
Using Sections to Help Manage Page Moderation and Named Pages
As discussed in areas on specialized sections in Page Name Management and Page and Comment Moderation, TeamPage allows sections to be configured specifically for the purpose of helping manage moderated publishing and use of named pages. When working on any sizable set of pages, creating and using these sections will prove indispensable.
These sections can be placed wherever sections can be used, such as in project newspages, in Profile pages or even in articles. Since it is generally not desirable to expose these sections to readers of a documentation project, you may not want to place sections that list published pages, etc. on the newspage of that project. However, you can:
1) Place sections that list articles only visible to users with Read Draft Articles permissions on a a documentation project newspage. Simply set the section option Show Section Title to Only if Section has Content. Since there will be no matching articles/pages when the newspage is viewed by someone without Read Draft Articles permissions, the section will not show at all.
2) Place the sections on the newspage of another project, such as the designated Moderation Project. In fact, if you have multiple documentation projects, you can consolidate sections for managing page moderation and named pages on the same newspage or Profile page.
Note: when using a section that shows pages in a draft state, draft pages will only show up in the section when the project containing the pages is set to Draft Mode (e.g. a section set to show only draft pages will be empty if viewing the project in Published Mode).
Using Labels to Help Manage Documentation Updates, etc.
Wiki-style documentation projects generally are organized by creating sets of pages linked by page names, rather then by using labels to categorize articles and group them into sections. However, you can also apply labels to articles, paragraphs and comments as an organizational technique to help manage such things as marking pages for revision, assigning tasks, tracking completion status, asking questions, etc.
For instance, the following techniques were used in a revision cycle for the Traction TeamPage online documentation you are reading. For this revision cycle, an outside contractor created draft pages, which were then reviewed, edited and published by Traction Software staff.
Note: As described above, a Moderation Project was used in order to keep all labels and comments involved in the revision process from being visible to people viewing the online documentation in its published state.
A label in the form "r41" was applied to pages that needed updating based on new capabilities and other changes made in a new enhancement release of the TeamPage software.
A "to do" label was applied in conjunction with that label to flag that the page had not yet been updated.
A section was created to list those pages to be updated (filtering for the "r41" and "to do" labels)
Another section was created to list pages in a draft state where the "to do" label had been changed to "done." This provided a list of pages ready to review, edit if needed and then publish.
From that point forward, users with Read Published rights to the Moderation Project, are able to see immediately by looking at the labels whether a page they are looking at in the Documentation project has been updated for that release (it will have the "r41" and "done" labels).
Labels were also used to indicate specific images in articles that a) needed to be replaced immediately or b) are slightly out-of-date, but didn't need immediate replacement
Labels were applied to comments made to the Moderation Project to indicate whether they required action by Traction Software or by the outside contractor
Sections were created to list Traction Software open "to do" items and contractor open "to do" items
In this case, the newspage of the Moderation Project for the Traction Documentation project ends up looking like this:
Using Email Notifications to Speed Interaction
When more than one person is working in a moderated publishing mode, setting up email notifications for changes made to articles/pages in a project can significantly speed up interaction. For instance, a person responsible for publishing articles can be set to receive an email notification when a draft article has the label changed from "to do" to "done." See Email Notifications for more information.
