rewrite in The WikiPatterns Pattern Language

Recently we've acquired Confluence and Jira from Atlassian, and although both are very well documented and detailed towards user interaction and functionality, there comes a point in every application where a custom manual must be made to not only tell the users how the application works, but also not tell the users other functions of the application (or worse, how the application could be further customized).

The reason for this is that, if you open your application up to a large company, and the users find out about the many possibilities of the application, then you'll be busy until the cows come home with custom configurations for each group of users that want something different. In the end, once you're done with all those hours of coding and other work, the user or group decide that it is too difficult to use.

In our case, we have custom configurations that we deem necessary, and the rest is kept a secret (unless users decide to get curious and start reading guides on the Atlassian website… at which point we tell them NO to any customizations). Its not that we keep info from them, it just comes back to the old quote of:

Give them an inch, they take a mile…

I configured Confluence, a wiki, and the first space I set up was a full blown manual on the functionality of the application from a user's perspective. Not only did I create a method towards new users to learn how to create, edit, and comment on their pages, but I learned a lot about the application along the way. As the manual (for both Confluence, then Jira) was created, I discovered many perks that an online manual could have in comparison to a printed or soft copy manual made in MS Word. Its one thing to read a new app, its another thing to interact with it.

• environment friendly… no wasted paper on needless printings of manuals that won't be read
• export option to export the whole space, or a page, to PDF to be printed for those who actually WILL read it
• easy updates to additional features and plugins as they come
• community type manual where comments on specific sections of information may benefit others who read it
• quick set up for things like macros and plugins or tool… why write out the whole macro and its parameters when you can copy and paste
• examples of functions and parameters are right there in front of you

There are many other perks to online manuals, above are just a few off the top of my head. But its actually saved me lots of time, and was fun during the whole process.