Situation

• powerful collaborative features are used to edit content in Confluence, but the user macros themselves are unversioned and difficult to document or share.

Details

• User macros are important. Despite their quick nature, user macros are the 'glue' that sticks together many sites, quick-fixing plugin blunders, create shorthand recipies combining macros from multiple plugins and placing notices and replacing obsolete or missing macros. (we have over 200 of these, some very complex).
• Authoring and maintaining user macros are collaborative. On even moderate sized installations there can be several system administrators that have access to the user macros. They are sometime authored by one person, broken during an upgrade (which needs to be noted), repaired by another, and new 'syntax' added by yet another person.
• Unlike regular wiki pages, they are currently unversioned. This obviously means we can't revert mistakes, see who contributed what elements, or see their comments as to why they made that change
• Unlike regular wiki pages, they can't have threaded comments. This is helpful for discussing transitions, strategy, dependencies, or details around a specific user macro. It would be good to have one set, shared between admins, and another set associated with the documentation described below.
• Unlike regular wiki pages, they can't be 'watched'. This would help notify admins when certain macros are being updated, or notify interested users when the macro (or macro documentation below) was updated.
• Unlike regular wiki pages, they can't be restricted to certain individuals. Not all site admins are equal. It would be good to restrict some of the higher profile user macros to specific users (not because of the access to the API, all admins are trusted with that, but because some user macros are used extensively and should not be updated arbitrarily)
• Unlike regular wiki pages, they are not visible to the regular users. It's not the code or the comments that need to be visible, however, it's a 'documentation blurb' that includes parameters, usage examples and description of functionality. These sections should also be version controlled, attributable, watchable and restrictable. In this case, however, we would like to extend the ability to edit these three blurbs, in wiki or rich text syntax, to regular users.
• Unlike regular wiki pages, they cannot be linked to. It would be helpful, for example, to say "Please see user macro [xxx]" or "user macro [usermacro:xxxx]" and have that link to the help documentation for the named user macro.
• Unlike regular wiki pages, there are no 'incoming-links'. It would be very helpful when refactoring user macros (due to a Confluence version upgrade, a plugin upgrade, or chance in functionality), to have some idea what the impact of that user macro was on our installation. To know how many, and which, pages use the macro would be great.
• Unlike regular wiki pages, they cannot be labeled. This would be extremely useful for categorizing our 200 user macros into groups, which helps with documenting and with the learning curve for new users and admins. (labels might include which versions they've been tested on, are they content or formatting, are they obsolete, temporary, core to our installation, related to a specific plugin, etc)
• Unlike regular wiki pages, they cannot be easily transfered between installations. It would be great to share them by letting regular users see the code (if desired). If that user is then an admin on their own install, the can quickly duplicate the functionality, improve the macro, and deliver it back to us tested.

Suggestion

• use some of the lessons learned from the regular wiki page user interface to enhance the editing and documenting of user macros

(appologize to Charles below for me not being specific enough in my first request)