Archive for the ‘Content Managment Systems’ category

Using Wiki markup without a Wiki

2007/05/17

Even with having Wiki as the main documentation repository, not all documentation ends up in a Wiki. Some documentation needs to be managed as part of the source tree – e.g. Readme’s, compilation instructions and similar. This information is usually either plain text or in some form of text processor format, mostly Microsoft Word compatible. Both have their selection of problems. Word documents are large, bloated, harder to version controlled and not readable in shell environment (try to cat or tail Word document :-)). The plain text format lacks visual structure and without headlines, bold/italic, font sizes etc is harder read.

Some projects I was working on were trying to use HTML as documentation format – but it was too hard to edit using “programmers editors” … and HTML generated by MS-Word is not much better than binary format from readability and version management perspectives.

One format that works amazingly well is a plain text with Wiki markup structure. There is wide selection of various markups, the one I like the best is the Textile markup (which is implemented by many Wiki systems, including Confluence). Textile is very easy to remember, us natural to read and gives the document enough structure without being in the way. Using Textile as “source markup” allows us to copy and paste the document content directly to the Wiki, should it be required. Textile can be also very easily transformed to full fledged HTML using libraries available for all languages of interest (in my case – C#, Java, Python, Ruby – and hopefully will find something for Objective-C as well) to convert it to HTML.

The best feature of using Textile is that some editors – namely TextMate on Mac – support Textile natively and show headings and font attributes properly even without pre-processing step. And with Preview function even generate HTML right away. The similar can be done using plugin in JEdit as well as in Notepad++ with this syntax file.

Project management using Wiki

2007/03/05

It has been half a year in March since we have started to use Wiki as main project management, collaboration and content creation tool. I think this is period long enough to look back and summarize what we have discovered, what worked and what not. This was not the first attempt to use Wiki in this context – however, it was first case when the result can be considered full success. I have tried (both in at-home and project environments) several Wiki implementations, notably JSPWiki,MoinMoin, FlexWiki, Wiki module for DotNetNuke and MediaWiki over period of about 5 years. During this process I have discovered by trial and error, which features are important in software development project environment and what are the conditions/consequences of using Wiki as main information hub.

Wiki selection

The Wiki engine we have selected for the biometric project was commercial Java-based implementation from Atlassian software Confluence. The main selection criteria was platform independence (we wanted OS-independent solution that could talk to variety of databases), technology alignment (to use in-house expertise), enterprise-readiness (possibility to integrate with other systems – issue tracker, security, ease of administration) and high user comfort ( easy of use for technical users, advanced features for developers).

Wiki and content creation

For software development, the content of the Wiki is not your main deliverable – it is the source code. Neither is Wiki the tool that is used to create or manage the main deliverable (source code) – this is the responsibility of source code management system. The content you can put into Wiki is mostly targeting the phases BEFORE coding and AFTER coding, and auxiliary information about coding during actual implementation.

In the “Before Coding Phase” we have used Wiki as main hub for both requirements, analysis and use cases. It was harder than it sounds because – let’s face it – the user comfort of the Web based WYSIWYG editor is not quite in the same league as the Word or even OpenOffice Writer. The more Office addicts and Word power users you have in team, the longer it takes some time to adjust.

The main advantages we have seen from going with Wiki was immediate visibility of the documents and no version control issues. No time was spent on emailing DOC files around, looking for latest and greatest specification version, or spending time integrate the comments from review. The analysts were able to work on live document, with full history of changes available any time (attributed to authors). When reaching the milestone, they could with one click generate the PDF snapshot, archive it or put it to document management system and move ahead. The full text searchability of the content has proven to be an important time saving feature – to achieve the same flexibility with Office documents you need to use something like Google Desktop or run OS-X or Vista.

Especially in the early stages of content creation, we appreciated a lot extremely dynamic cross-linking capabilities of Wiki. If you have ever tried to maintain Word document with many cross references and internal links, you may have an idea why :-). It was much easier to create chunks of content first and worry about structure later. Confluence puts pages into tree structure, which can be used to organize your content into logical, coherent units. It also provides very easy way how to rearrange page position the the tree, including subpages. What was very useful, were actually page comments – if you were not sure about changes, you could add comment that was carried around with the page, eventually incorporated into page content. Another very good feature we have used was tagging: it allows to create multiple additional structure, completely independent from page tree, with single page having many tags and “appearing” in multiple places in the structure.

During actual coding, we have used Wiki document everything that was related to project builds, configuration, test data, database loading procedure, as well as the base for creating the test cases.

In the “After Coding Phase”, Wiki is the ideal place where you can put information about releases, installed builds. Confluence integrates very well with other Atlassian product – JIRA Issue Tracker – and using both, we could easily use Confluence pages as details for the bugs and issues in JIRA as well as the other way – refer to JIRA or even document current list open issues in the particular project release. Wiki was the place where the README.txt nad “Installation Guide” were created – way before they actually needed.

We have had several discussions on how far can Wiki replace the document management system and came to the conclusion that it can – in limited way. What is Wiki perfect for is the content creation and collaboration on “living” content. Because any page can have zero to many attachments (binary or PDF) you can, technically, use it as repository for released versions of the document (e.g. set of pages rendered as PDF or even copied into Word document if you must).  There are many way how to implement it – either by creating separate workspace, or using tag RELEASED or simply by page naming convention. This is however not solution with the same strength as dedicated document management system – it is lightweight, uses semi-automated workflows and requires some discipline. It really depends on your particular business case (number of users, documents, business processes) whether you want to use it or go after some bigger (and often much more expensive) solution.

Wiki and project management

Right after ubiquitous Microsoft Project, Wiki can easily be the most useful tool for project manager.Wiki will never replace MS Project, but it complements it in many ways. It can contain both information that is either too high level to be managed in Project, or too detailed (like detailed work breakdown). It can be also used as communication tool by providing the PDFor JPG renederings of current project plan to the team and/or customer – as not everybody has installed MS Project.

In about middle of the project Peter defined “project blog” – subtree of pages, indexed by the weeks, where team members documented changes, news or suggestions for the others. Unlike emails, the information was available from any place, fully searchable and could refer/be referred from other Wiki pages. Speaking of email, Confluence has great feature that we have not really utilized: you can use it email repository and make the email search-able, visible – turn it to discussion forum or knowledge based. In every project, email is hidden reservoir of know-how which often goes uncaptured …

Cost of using Wiki

No, I do NOT mean the amount of money you have to pay for your software license. Even if it not negligible, we all know that the true cost of every software is mostly in human labor needed to keep it alive and well. As the person being responsible for installing, administering and managing data for Wiki, I am happy to report that this cost is actually very affordable.

After initial install which takes (depending on database selected and amount of integration points and your familiarity with Tomcat and web application configuration) between 20 minutes and 2-3 hours, I had only one case when some maintenance was required: to increase amount of memory available for the JVM. The rest was done automatically. Confluence does every day automated backup which put the actual pages (as XML export format) plus attachments into ZIP file – all you have to do is to include the backup directory to your system backup, or make sure it sits on some secure RAID-5 or mirrored disk device. Being slightly paranoid when it comes to backups, I have chosen both, and in addition I have also scheduled automated DB backup to save the page content in binary format as well.

Wiki and mobile workers

In order to use Wiki, you need to have connectivity – to Internet in general, and specially inside the network where your Wiki installation lives. Which may not be always available. With Confluence, we found out that you can have at least read only access to all the knowledge contained in the Wiki. The key is export functionality. Workspace can be exported either as PDF or as HTML tree (including the attachments). Both can be viewed online (with limited search functionality). This is very feasible solution for e.g. offsite support where connectivity to source Wiki is not available.

Criteria for success

So what makes Confluence special that using it succeeded where other Wiki’s did not ? Few things, IMHO. First of all, is easy of use and generally very polished user experience. When you are editing content, the UI you have is very good for Web application. It does save your changes, does not loose your content. You can switch between “markup” and WYSIWYG. With single click, you can convert the page to PDF. Very easy way how to create tables. The copy of the text from Word or browser actually can be posted into Wiki editor and keeps formatting. Linking pages is very efficient. Inserting images (including thumbnails) is extremely comfortable. It provides very powerful macros – such as picture gallery, or list of all child pages.

Second are the enterprise-readiness features such as security. Plug-gable authentication. Automated backups. Good administrative interface. Extensibility through plugins. Open architecture and availability of the source code (no vendor lockup). Ease of install and very low maintenance. Open data interchange format (XML). Very easy way how to track changes and “one click undo” should the information be deleted or damaged.

The third factor is related to calendar year and shift in perceiving. Unlike in 2002-2003, Wiki’s are mainstream and everybody is aware of their existence and their value (see Wikipedia for the most visible example). General shift towards using more on-line application and less dependence on locally installed software (thanks to Google and others). User’s experience improvement thanks to Web 2.0/AJAX features. Much less discomfort of working with data that “out there”, not on your local machine.

Wiki's are everywhere …

2006/11/21

Since the beginning of the biometric security project, we are using an excellent enterprise-level Wiki Confluence as knowledge repository and main team communication tool. I was not sure at the beginning, how will the Wiki approach work for all the people on the team, mostly because once before I already tried it and had not much success of introducing the idea. It was few years ago and the Wiki engine I used were nowhere in the same league as Confluence, but main problem at that time was probably the users’ mindset. I am happy to report that this time it worked really really well. I am not sure whether it was because of the fantastic user friendly features and capabilities of Confluence, or because the general awareness shifted thanks to sites like Wikipedia and people got used to the idea of user created content … The truth is that Wiki’s are mainstream now – inside or outside of the enterprise space.

And here yet another proof for that: Microsoft launched the MSDN Wiki that merges content provided from MSDN documentation with user added/edited content. I think it is an excellent idea – MSDN documentation certainly can be improved and enhanced in many places and letting people who actually use the product contribute to the documentation content, is the right way.

The MSDN Wiki engine is right now IMHO nowhere close to to Confluence level of user comfort. From what I have seen so far, Confluence is the Lexus of the Wiki world.

Here is the question: can largest software company in the world deliver something at minimum comparably as good (or better) as creation of a small, opensource-based softwarehouse from Australia (which using, on top of all, Java and Tomcat as the platform) ?

We will see.  Maybe.  Let’s hope.