One of the challenges commonly faced in development is sharing and communicating the myriad solutions, procedures, and configurations we make throughout a project. To help tame our complex environment, our team has incorporated a Wiki devoted to documenting our development environment. There are many Wikis out there such as MediWiki, WikiSpaces, and SharePoint. We chose Confluence because it has robust support for creating a variety of content. It can track meetings, create blogs, but the feature we use the most is the main feature of the wiki, the page editor.
Confluence’s Page Editor
Confluence’s page editor allows us to create our own content, organize it, and then it’s automatically added to the Wiki’s search engine. The Page Editor allows for many different types of content to spruce up your entries, such as images and code blocks.
Page Editor in Practice
So what exactly do we store there? The root or our Wiki contains four main topics:
- Developer Guide: This contains anything and everything a developer needs to know to begin work. It covers the software used, how to set up and run those tools, and an explanation of each web or java project that comprises our application. We also keep step by step instructions on how to build the application for deployment and we also maintain a set of guidelines on how to best debug, document, and unit test our code.
- Knowledgebase: This contains information we’ve picked up along the way. We cover code examples, additional Eclipse plugins, and an introduction to using our JavaScript framework.
- Troubleshooting: If you run into a problem with your development environment and find a fix for it, this is a great place to document your experience. If you’ve spent three or four hours fighting with Eclipse and Googling for answers, it just might save someone else that effort later.
- Production Setup: Step by step instructions on how to install and configure our application to production.
Adding Images with Confluence
While the Confluence editor supports the usual text formats, such as headers, hyperlinks, and tables, the feature that we encourage using is the almighty picture. Listing the steps to perform a task is good, but having a screenshot of each step is priceless. For example, the Eclipse development tool is extremely flexible and supports many programing languages and plugins. Unfortunately, that flexibility adds complexity. Just figuring out which “Properties” window you need to change can be challenging but a screenshot showing exactly which Properties window is needed and which fields to change can make a huge difference to the uninitiated.
Confluence Code Block Macro
Confluence also provides a Code Block macro that formats code examples and snippets adding emphasis and formatting that is easily recognized by developers. Using Code Blocks instead of screen shots provides the added advantages that the content is both searchable and can be cut and pasted if needed. This is especially useful when documenting installation steps that require typing in commands from the command prompt. It has several built in formats including Java, JavaScript, and C#.
Confluence’s Page Editor is a valuable tool for capturing information needed by the development team to ultimately improve communication. While it’s true that there is a certain amount of smug satisfaction that comes with uttering the phrase, “Did you check the Wiki?”, knowing that there’s a well formatted, thoughtfully constructed, and thoroughly documented solution to most of our questions makes it well worth the effort of setting one up. Gone are the days of sifting through Outlook looking for that “magic email” containing that solution you vaguely recollect from years ago. Those days are certainly not missed.