Wiki For Documentation

(2007-06-07) The point here is to explore whether or not wikis should be used for documentation, basically to discuss the pros and cons. Our company runs its own wiki (PmWiki for those interested) and we're debating its usability for technical documentation of our software.

(NOT FINISHED).

Pros

Is a ready-to-use publishing system
Content is immediately available for viewing and further editing
Allows for easy documentation collaboration on multi-developer projects

Cons

Difficult to facilitate organization, due to:
- lack of organizational facilities
- using a syntax within content method for organization versus form or GUI driven methods is much more difficult and time consuming
- steep learning curve to use syntax in content to facilitate organization
Lack of good web design principles for ease-of-navigation for documentation (wikis are ad-hoc from a navigational perspective)

(PLEASE ADD TO THESE PROS & CONS)

We already have a very nice project management system and often the descriptions of project and tasks from it becomes the origin of a project's documentation. But the two systems are separate and cannot be easily used together.

(db) Can you tell us more about your project management system? Is it homemade? Are you using a wiki?

Yes I can... BEGIN by John M (2007 06-12): our project management system (simply named the Project Management Center (PMC)), is a hierarchal system for describing and organizing software projects. The application is web-based and highly conducive to collaborative development over internet. It is very much different from any other similar system I've seen, and it is not a code repository system like source-forge. As matter of fact, our PMC would work synergistically with a source-forge like system.

Projects are organized by Assignments, which are 'assigned' to a specific developer. The Assignments are then broken down by Tasks. Also, Projects can themselves be organized into Project Groups so that large projects can be subdivided and developed by separate development teams, but be tracked concurrently.

PMC Specs/Features include:

Database driven (MySQL)
Written in PHP
Good use of Remote PHP (or AJAX if you will)
Tracking systems include:
- Best Bug Tracking system I've ever seen
- Project/Assignment/Task Trackers (with built-in scheduling controllers)
- Developer Tracker (really a developer's planner/scheduler)
Communications facilitites, which include:
- 'Development Meetings' pages (functions sort of like an enhanced BB threads)
- Internal messaging system (sort of like an email)
- Live Chat system that's not an IRC channel, but maybe could or should be
- Developer Alerts (various notices about deadlines/timelines and communications)
... AND A WHOLE LOT MORE!

It would take much more time to provide a comprehensive description than I have here. But in a nutshell it basically takes developer data (daily work hours and overall work schedules to include vacations and other stuff) and uses that data against the time estimates input on the Task level (FYI, all data for timelines is at the Task level). Then the developers' data is taken against the Task data to provide a real-time analysis of schedules/timelines and such.

Like I said, this is the coolest project management system I've ever seen. It totally blows away MS Project (or whatever it's called). What makes it so good is the hierarchal structure given to development projects and the effective use of relevant development data, which is of course the assignment of work, the amount of time a developer is going to work, and the time estimated for the work. Most other systems just let you describe a project and then create a list of tasks and tag those tasks to a developer. That's just not enough to provide a comprehensive project 'management' system, and that's why we addressed everything we did with our PMC.

Final note, we have always debated whether or not to make this an open-source project. If anyone is interested in such a system, please let me know on this page and maybe we'll go ahead and take the time to set this up on source-forge or something. END by John M: (2007 06-12)