Customized "macro directory" has multiple benefits

[#1]

As a brand-new wiki space admin, I needed to discover all the add-ons and macros that were available to me and to the average user. Over 230 items were listed in the macro browser—a bit overwhelming! I wanted my own list to speed up browsing, organize my "toolbox" and record my own notes.

This personal list became a resource for the entire wiki community, providing value beyond just organizing my thoughts. Now I feel vindicated for taking the trouble to create it!

Creating the v1 list

My method for creating the initial list was clunky and goofy, but effective. (I'm not a system admin.)

I opened the macro browser, then used my mouse to drag down and select all the items in the macro browser, then used Control+C to copy.

I opened a blank MS Word document and used Control+V to paste. Then I used Insert Table > Convert Text to Table.

Since the macro directory info wasn't uniform, I had to massage the table and text into a consistent list. It didn't take as long as I thought, but if there's an easier way for a non-system-admin to do this, please share!

I set up columns like so.

• Icon - what users see in the macro browser
• Macro name - ditto
• Supplier - vendor (such as Confluence or Adaptavist)
• Documentation - URLs to official documentation and/or other helpful pages
• Description - from the macro browser, plus my own notes
• Macro name in markup - text used to insert macro via markup (such as {chart} or {livesearch} )
• Example page(s) - URLs to pages demonstrating macros

Additions to the V2 directory

I populated the table gradually over time, adding links and information about macros as I used them in wiki pages.

I added instructions on how to find a macro's markup name using the Wikifier RT tool, and instructions on how to use the markup name to find pages containing specific macros. This information came in handy when we investigated how many pages across the wiki were using a defunct add-on. It also came in handy when I was looking for pages with redirects, reports that needed a setting change, and sequence diagrams.

Here's a partial snapshot of the page today.

Recently I linked to more example pages, to be used as part of a "wiki upgrade checklist." A system admin or wiki space admin can work their way down the example page column, visiting pages to check for proper display of each add-on. If the example pages look good, chances are the macros are working correctly across the instance.

More benefits

Beyond those benefits, the macro directory helps me and others on a regular basis.

• I can quickly browse all available macros at once, which is especially helpful when I'm brainstorming solutions
• I can quickly click through to the current, updated links to macro documentation, since some are out of date in the macro browser
• I can sort the macro list by supplier / vendor to understand which ones are related
• I highlight useful, related and/or uncooperative macros for the benefit of all end users
• End users can check out example pages to see if a macro does what they want before going to the trouble of creating their own page.

What's next

The macro directory will be copied to the staging area before the next upgrade, so there will be plenty of time to check out how all the macros and add-ons look in their new environment. After the upgrade, I'll create a new list and compare it to the current one to refresh my listing, but I expect the process to go faster this time. 

If you've created a macro directory for yourself as an admin or for others as a user I would love to hear about your implementation.

[Kat Warner]

Thanks for sharing your steps. I can see how useful this documentation would be and can image use cases for a column documenting the known usage (not used / widely used, purchased for a specific team's need etc) and (links to) test cases for post upgrade testing.