Approval Macro

A page approval plugin implementation has been developed by Saikore. More details can be seen at the home page.

Often in organisations, knowing who has read and who has approved a document are very important things. However modern document management systems make read and approval checking very tedious to implement and monitor. I'm wondering if we can't come up with a simple agile/Wiki like solution to this problem.

Simple Macro Approach

Perhaps it could be as simple as a macro like:

{approval:Bob, Jim, John}

Name	Read	Approved
Bob
Jim
John

As people start to read an approve the document, it might end up looking something more like this:

Name	Read	Approved
Bob
Jim
John

How does it get read or approved? Simple links really. Imagine you are John who is logged in and looking at the page, you would see something like this:

Name	Read	Approved
Bob
Jim
John	Mark read	Approve document

Simply by clicking on the links, you indicate that you have read the document, and give your approval for the document.

Why read and approved as separate steps? Well you might read the document, click the 'read' link and then add a comment requiring more information before you're willing to approve it.

It would be improved if the macro actually coloured the backgrounds of the cells I think, to make it look more like a FatCow test result. When the table turns green, your document is approved!

Thoughts?

Advanced Macro Approach

The following points give a very rough specification of how a simple 'wiki style' approval system might work.    I describe it as 'wiki style' because it does not require any administration and hence can be managed by the wiki community.   If you edit these specifications, please keep in mind that the approach taken here is to make the process as simple as possible for users.   

General Requirements

• Anybody can register as an 'approver' of any page.   This would be done by clicking on an 'approval' icon which could be a tick icon (next to the the star and envelop icons at the top right of a standard page  e.g.    )

• Users would be able to see a list of all the pages (and their approval status) that they have registered to approve.   This could be a similar mechnanism to the one that allows users to see favourites or watched pages.

• Pages with registered approvers would display the list of people who have registered as approvers.  This could be in a table at the top (or bottom?) of the page, like this:

  Name	Read	Approved
  Jim
  Bob
  Fred
  Jo
  Jill	Mark read	Approve document

• Note that the table above is what 'Jill' would see if she viewed the page (and has registered as an approver).   Jim has read and approved the page, Bob has read and rejected the page, Fred has read the page, Jo has not done anything and Jill has not yet done anything either.   Jill can mark the page as 'read' or 'approved' (or unread and unapproved as per the page state) by clicking on the links.  It may be better to have the page automatically be marked as 'read' after a user first views it.

• A page would be marked as 'unapproved' until all the people in the approval list have approved it.  An unapproved page would be marked as unapproved by some bold red text or background (or something....)    

• Once the page is approved, it would have a special version number assigned (and perhaps a special label assigned such as 'APROVED_V1.1').  Some ideas from software version control might be applied here.

• If a page is changed after it was approved, the approval (and read) status for all users would be reset to blank.  All users 'read' status would be reset on any page edit.

• Users who view a page that is not approved would be able to easily navigate to the last approved version.   By default, the latest version would be viewed, but the user should have a preference somewhere so that their default is to see the last approved version.   The users choice for each page could be persisted per page.   There would need to be a very obvious visual indication of the approval state of the viewed page and easy navigation to the alternate version.    In this way new versions of an approved page can be easily accessed for reapproval developement.
• Approvers can unregister without affecting the approval status of documents they approved in the past.   However, this may affect the approval state of pages that are currently unapproved (i.e. if the user was the only person left to approve a page and the users unregisters, then the page would be approved.

• There may need to be some way of automatically unregistering approvers if they are inactive (account closed etc.)
• The addition of macros on a page can invalidate the version number of a page by allowing changes without incrementing the version.    One way to get around this problem would be to prevent any page authorisation actions on a page with a macro.   Since this would disqualify many pages, some macros could be made acceptable if they identify themselves as being 'approvable'.   This could be done by introducting some sort of macro property (the default would be unapprovable for legacy macros).

Potential problems

This approach was conceived for an intranet application.   It would work because people on an intranet can generally be trusted to some extent and are at least accountable.   There may be problems with this approach on the Internet because casual users would be able to register as 'approvers' and then disappear, leaving a page that would never be approved.    This could be used as a form of vandalism.

Dynamic Data 

Dynamic data can invalidate the approval of a page because the page can change without an edit.   For instance, the {include...} macro could show different text based upon what is in the included page, independant on anything in the controlled Confluence repository.    Hence, using some macros, an approved page could change without the authorisers knowing about it.   

One way to get around this problem is to make macros and plugins 'unapprovable'.   Any page with a macro could not be approved.    However, some macros do have 'approvable' behaviour (such as the table of contents {toc} macro) and it would be very desirable to allow these macros to be used in approved pages.    One way to facilitate this is by adding an 'approvable' property to macros.   By default, all macros would not be 'approvable', but if the macro developer sets the 'approvable' property then the macro could be used.

Other Ideas

See http://meta.wikimedia.org/wiki/Article_validation for an extensive discussion of the issue in the Wikimedia community.