How can programming documentation be structured?

Hello. I've been tasked with setting up a wiki system for our programming staff for documenting the various systems we work with. What I'm wondering about is if anyone has tried using Foswiki for this before, and if they might have some tips.

For the sake of example, the first system I wish to document is a transaction processing system consisting of several databases, such as DAILY, MONTHLY, and HISTORY. Each of these contains various tables, functions, and packages of code. There are a number of interconnections between these databases.

Some of the tables repeat across databases. For instance, there's a table called GPS_MASTER that is mirrored across all of them.

My vision for this system is for every object (or at least the most important ones) to have its own topic, explaining how it works. Where it refers to other objects, sometimes in other databases, it will provide a link, so that the reader can immediately jump to that object's topic for further details.

But I'm not sure how to structure this.

Given that each database has its own namespace, with identical object names shared among them, this would seem to require a separate web for each database. And this is just one of (hopefully) many eventual systems, so I imagine these would be subwebs of a web for this whole system.

Another thing I've found is that when you follow a link from a topic to a page that hasn't been created, the new topic will be a child of the first topic. This behavior is illogical in this context. Is there any way to disable this behavior? The best idea I've come up with is to create a stub topic for every single object.

Has anyone been down this road before? I'd love it if someone could point me in the right direction, so I don't end up investing time in some flawed design. Thanks a lot.

-- JamieSchirf - 20 May 2010

I don't think there is one right approach. I think using multiple webs can work, using topic names as identifiers. You could also use data forms with fields Database, Table, Function, and not use topic names as identifier.

You can change the NEWLINKFORMAT macro per site, web or topic, just redefine what is written as default in DefaultPreferences.

-- ArthurClemens - 28 May 2010

Thanks. I've actually been having success with one web and careful use of identifier names and hierarchy. But that data forms idea certainly sounds like it has potential for this. Thanks again.

-- JamieSchirf - 04 Jun 2010