DocCollab Tool

Using e-mail to start and close support tasks causes these problems:

• messages are stored in each other's private mailboxes, without public access to the information.
• the know-how and knowledge of a team member that leaves is lost.
• tips and tricks are passed verbally to one another, sometimes over and over again whenever a new team member arrives.
• many tasks are executed through small commands, which are seen as a collection of tips and tricks, but no single person knows them all.

The first problem would be easily solved by a trouble ticket system. What prevents us from deploying such system is that client doesn't want to learn anything new and some team members don't want to learn any new system. Any kind of trouble ticket system must be practical, intuitive, simple (small learning-curve) before my team leader even considers evaluating it.

The second problem would be solved if we took the time to document our actions and tasks. A set of best practices, tied to a repository of tips and tricks, would be great.

The last problems would be solved if we kept a common/shared repository of tips and tricks. This repository needs to be categorized, since some tips are for database, some tricks are Unix commands, and so on. This repository must be of easy access and simple to manage.

But the major problem that kickstarted my search for / learning about WikiEngines is the need to document our analysis of the source-code of one of the major applications we support.

In short, we need a simple, pratical, easy and common documentation and information management system with knowledge repository capabilities. How well will DokuWiki perform?

DokuWiki has been performing well. Two of the 5 team members are using, and at least 2 more are curious about it so they too may start using it. We are mostly documenting source code analysis, although I've added several code snippets to a common repository and I've also added a small set of tips and tricks. We have not yet managed to integrate an Issue Tracker, to fix the scattered e-mail messages problem and workbook mono-user problem.

One of the “big” experiences extracted from this scenario was the namespace structure. We started with a namespace “Projects” for all our running projects. Soon we discovered that a page holding project's notes required that instead of one namespace we needed several namespaces, one for each project. We end up moving pages from Projects:<project_name_1>.notes, Projects:<project_name_2>.notes, …, Projects:<project_name_n>.notes to ProjectName1:Notes, ProjectName2:Notes, …, ProjectNameN:Notes. For this, it would be handy to have a Page Move/Rename feature, but we managed to execute the change with just the help of search function. The search highlighted all pages linking to the project's note pages. Again, another cool feature would be BackLinks, to assist us in this task.

Another “big” experience was the template for specific pages. It works as a content skeleton for similar pages, but under different subjects. For instance, we have to document the server-side processes of one of the projects, and each process page has the same content structure. We created an offline empty-process-page-template that we copy and paste into the GUI editor before adding the specific content.

The major problem we're facing is that Internet Explorer doesn't handle well the ALT-L inside the GUI Editor neither the upload of media. We don't know exactly what's wrong, since under Mozilla everything works fine.

The two of us using DokuWiki appreciate its following features: raw text file, simple yet visually uncluttered aspect, practical syntax and GUI editor, syntax highlight (we must document alot of code, and tips and tricks mostly in SQL), section editing and automatic table of contents.

The editing lock mechanism, plus all the bugfixes, and the possibility of using CustomEditingForms are just what everyone wished for. Now the Wiki site is being used, still not by everyone in the author/editor role, for reviewing and tracking project progress. The DokuWiki community, specially Andi, jed and sb, were fundamental for the basis of the assurance on the WikiEngine. We now consider this tool to be one of the most adequate (well-suited) tools for the generation and browsing of technical documentation, produced in a collaboration-mode. We're now considering the best-practices to apply in linking the WikiPages to the automatically generated Doxygen pages.

Now that the Wiki is fully used by the team, although only still 2 of the team members are active editors (authors), some needed and missing features have been identified:

• BackLinks. With BackLinks, one can view the relationships between documents, which helps structuring the content in an easy way to be “navigated” (browsed by).

Backlinks are now supported

• Export Page. Only a few documents are required to be sent out of the team, with some information that the team expects to be useful and show-off the advantages of using an WikiEngine. But DokuWiki has no “nice” Printer-Friendly View-Mode neither is able to export to PDF while keeping the exact content (text and media files) and styles.

DokuWiki has a CSS stylesheet for printing – when printing all menu stuff is hidden automatically so there is no need for a special print view. PDF export may come in the future, but is currently not at the very top of my todo list. Andi

Andi, it's not that. The printout would be OK (I assume) but we need to move static HTML pages from the WikiSite to outside the team. Not that it will be a standard procedure, we're just trying to “advertise/promote” the usefulness of Wiki in documentation collaboration. A export function is needed: what we do now is open Mozilla Composer, remove the header, footer and edit section links, save the file, include the css and media files and package it all to be sent by e-mail, so other can see the documents. We even include the TOC, which is useful. Still, each one is building up a sense of usefulness in the application of DokuWiki in collaborative documentation.

Ahh now I understand. Hmm export as HTML simply without headers should be easy to do. PDF export is as I said planned for some time in the future but meanwhile you could simply print to PDF. Acrobat's distiller does this very well on Windows and Macintosh and there a some free solutions (eg. using some combination of virtual printers and ghostscript) available, too. This way you could use the print CSS for export to PDF — Andi

You're absolutely right. Just have to see if the team will grasp that and doesn't find it too “hidden” to remember to use it. I think a “Export→PDF” button would be more friendly than your suggestion. In any case, that solution is good enough for the “temporary purpose”. Thanks. Still, it means that users must “install” an extra package for some nice-to-have feature in DokuWiki. I'm glad you're considering this feature for a future release.

I'm thinking about this: now that DokuWiki can export the documents of a namespace, through XML, can that be useful for an export function as the one our team now needs? The WikiEngine is running from my workstation, which is only accessible by internal team members. – 2004.09.23.

Well no. Only a list of documents is exported (as RSS or ATOM) so this is probably not what you have in mind.

— Andi

One of the biggest improvements is the warning message preventing users from leaving edit-mode without saving the changes made to the document. We expect the documentation process flow to be even more fluid now, although we're now facing the Editing Lock bug.

It has been finally accepted. The team now uses DokuWiki to produce all internal technical documentation for the project in hands. All team members are active readers/writers, although two of us have more experience in using the engine. That experience has been helpful in guiding and supporting the other team members questions and doubts. We're also actively sharing ideas on how to better use the documentation and the engine. One of our biggest efforts is now being driven by the CodingEnvironment experience. Expect no further log entries in this document.