Quote:

Original post by gstation Quote: Original post by Sik_the_hedgehog So, considering what I've read from the posts in this topic, I've reached the conclusion that it'd be cool if there was some kind of specialized wiki that has extra functionality to make documents for presentation in paper easily. I wonder if such a thing exists =P A very good question. I'm wondering what's the answer myself. Since I'm searching for a good wiki solution, I'll post a solution supporting this if I'll find one, but it would be great to checkout solutions that people have already experience with.

In my last job we made documentation in Wiki form, but had to supply PDFs to some parties.
The work-flow we ended up with was:
1) Browse to wiki page in browser, Open Word document
2) select Wiki content and copy
3) paste into Word doc
4) Repeat steps 2/3 for different wiki pages
5) Clean-up formatting errors from the HTML->Word copy process, insert page-breaks, ensure headings are correct
6) Print Word doc to PDF file

From my personal commercial experience of having used a wiki for a game design:

- ensure every page is categorised and sub-categorised. otherwise there can be parts of the design that nobody sees. (Nobody is going to recursively click every single link.) It's useful if individual designers take sole responsibility for certain categories.

- ensure you can produce hard copies of these categories. Again, this is primarily because people will not and can not trawl through every possible linked page to collect all the relevant specifications. But it is also easier to use in meetings, for writing notes on, etc. Each should stand alone as a fairly decent sub-document, with external links existing just for reference. otherwise you end up needing to be familiar with the whole doc to get anything done, which means you've lost most of your benefits over a normal linear document.

- ensure that you have the ability to lock page edits and force future amendments to go through an approval process. Designers have a tendency to go back and 'improve' and 'clarify' their designs after you've already started or even finished implementing them, thinking they're being helpful or diligent, but essentially leading to a discrepancy between design and implementation. This then causes problems when QA find that discrepancy and file a bug against it. The history feature is not enough for this - nobody is going to rigorously compare your source control commit times to the wiki revision history until the problem has already arisen. Lock the pages when they're given to the coders. This is a management issue rather than a technology issue, but the technology makes it much easier to bypass the management.

- ensure that designers 'own' every wiki page about the features they work on, keeping them updated and removing invalid ones. otherwise pages can end up outdated or orphaned as the design evolves, but a coder or QA person looking for information on a specific feature could find this wrong information and waste time acting on it.

- beware of discussion or brainstorming pages when your wiki is being used for the authoritative design. these can clutter up searches for that authoritative information, and often end up containing information that should be in an authoritative page. Use a separate namespace if your wiki provides such a thing to keep the normal searches free of this noise. The MediaWiki 'Talk' or 'Discussion' pages are a good way to handle this, leaving the main pages with the official docs.

So to conclude what was said before, the design document should be printable as a single document containing images and charts. It may be edited maybe by more than one person. It should be possible to lock the document or parts of it so that the implementation may be checked against the document at some later time. Version control and access restrictions are also important.


1) One solution would be to write down everything using Word/OpenOffice and pass it around as a single file via email. This allows printing as a single document, but makes it harder to edit the document by more than one person at the same time. Either there is one author managing a master copy or the "Who has the latest version of the document?" disaster begins.

2) Using a wiki allows to do parallel edits, user permissions make sure that only authors may edit. By revision control also changes can be tracked and old content may be restored. However to convert many wiki pages to a single document requires tool support and some rules the authors have to follow.

3) Something in between is to use a system like "TiddlyWiki" or "Wiki on a Stick". All data is stored in a single file that may be passed around instead of a word document. But in addition to a word document additional information may be stored in the document.

4) Another solution is to use Latex and Subversion. Again by using subversion, the document may be edited in parallel and access restrictions may be applied. Also a subversion repository may already exist for the code. The use of latex allows to write down the documentation in a single document which is nicely formatted.


From my personal experience solution 1 works fine if there is one author only, but becomes complicated if there are more. Also backups of the document should be made regularly, version control is performed by the word processor. Version 2 is fine, but converting the wiki pages to a single document is not so easy, esp. if the document should look nice afterwards. Option 3 was not tried yet. Instead option 4 worked very well for me many times. Since latex files are text-based, they can easily be managed by subversion and changes may be merged, even if there were conflicts. (Eclipse+Texclispe+Subclipse is a nice combination for instance.) And the backup of the document is automatic.

Hey All,

I happened to notice that my app, ZuluPad was mentioned here. If any members of Gamedev.net want ZuluPad Pro, I'll give 50% discount within the next 30 days. PM me or contact me at http://gersic.com/contact.php for info.

Thanks,
Tom