The WikiGnome's guide to maintaining the InCommon Federation Library
Introduction
(The "I" and "me" in this guide is Albert Wu, the original author of this guide.)
This WikiGnome's guide is my attempt to explain my thought process when I introduced this new layout to the InCommon Federation Library in 2019. It also captures what I believe are important guiding points to remember to ensure changes to this library continue to be relevant, sustainable, and hopefully stress-free.
I learned early in my wiki journey that maintaining a wiki is a lot like gardening (RIP Wikipatterns.com). It really is true. It takes patience, planning, flexibility (Mother Nature doesn't care what you want) and consistent attention to those small but important details.
This guide, like the Library itself, will need tending to from time to time as technology and needs evolve. Don't be afraid to update this guide as part of the ongoing gardening activities.
Guiding principles
These are a few bits I try to keep in mind when I work on a wiki. I do so to keep myself from becoming distracted by the nearly infinite possibilities when it comes to designing and publishing web stuff. They may seem silly, but they do keep me focused on the real reason I look to a wiki as a content platform.
- Focus on content - Keep the content accurate and fresh; make sure your content easily understandable and findable. No one likes snobbish stale bread. Content is like bread.
- Tell a story - A wiki is (often) more than a mere collection of pages. It is worth spending time to make sure the collection as a whole tells a cohesive story and that there is a logical progression to the material.
- This is about you readers - When writing, approach it the way your intended reader would like to digest the material. Don't write as if it is your personal notebook.
- This is a wiki. After 20 years of tending to wiki's, I've learned that things work best when one adheres to the wiki's namesake idea: wikiwiki. Keep things simple. Keep things lightweight and nimble. That means:
- Don't over style - While good theming and layout can boost readability, going overboard on a wiki platform can make ongoing maintenance a nightmare. Tread carefully.
- Work with the tool - This is Confluence. Don't turn it into a development platform. Take what it gives you. As much as possible, learn how to take advantage of the baked-in features (and compromise on those non-essential "requirements"). Resist the urge to reach for those extra plug-ins. They are great for solving immediate challenges, but you may regret it when Confluence upgrade time arrives.
- Don't let the tool distract you. Confluence isn't perfect. It has plenty of silly bits (more on those below). Do they really stop you from doing what you need to the point you have to stop to evaluate new tools? No? Great. Work around those silly bits. (This Library is a result of a lot of "damn u Confluence. Fine I'll do it this way then")
- Confluence isn't a full featured content management system. If the Library has evolved to the point where it outgrows Confluence's capabilities, bite the bullet and migrate the content to the right platform. Just be very sure those needs are strategic needs worthy of the migration pain.
- Keep the content semantic. If you are creating content directly within Confluence, see "Don't over style". If you are copying and pasting from another document source (damn you Confluence), every once in a while going into that HTML view and clean up the junk.... Ya it sucks, but this is gardening. Someone has to pull the weeds.
Content scope
The InCommon Federation Library is meant to, as its name suggests, be the online library for all things InCommon Federation. Specifically, we are talking about the materials made available to the public audience (InCommon Federation Public Library?).