Clarification of Question by
mathtalk-ga
on
14 Jul 2004 18:45 PDT
Hi, maniac-ga:
I'm not interested in the technical details of setting up a Wiki, but
in how a Wiki has been used to do database documentation.
Most Wiki's have a focus or purpose, e.g. as an encyclopedia or (in
the case of c2.com) as a discussion platform for software design
issues. I'm interested in seeing an example of a Wiki being used for
database documentation.
Assume the database is relational, if you like, and that a data
dictionary and links to table schemas, etc. are available to support
discussion of business logic (requirements for stored procedures,
triggers, constraints, etc.).
As I tried to express in my Question, I think a Wiki could help
address a lacuna that I've experienced with software projects, one
that has been commented on by lots of folks from structured analysis
to object-oriented to eXtreme Programming fans. The procedural
aspects of a software project are usually documented in greater detail
than the pure data design aspects. By this I mean it is easier to
write down "this code does this" than it is to paint a wholistic
picture of the data entities underlying the application and the
"business rules" that govern their care and feeding.
The procedural aspects tend to have a big picture to nuts-and-bolts
detail spectrum/axis along which to organize them, but this purely
hierarchical arrangement is not great for searching. Throwing
everything into a big directory and grepping on search terms is
certainly one approach, but a rather hit-and-miss one in my
experience. One often cannot find something and then has an
uncertainty about whether the documentation needs to be created from
scratch or a better search strategy is needed.
With data entities the organization is more combinatorial.
Relationships and attributes exist in a natural context of the
application, so navigation from one entity to another or to
properties/methods of entities is fairly immediate (if done right).
Thus my interest in how a Wiki could be used for such a purpose. It
would provide a fairly immediate gratification to the user, either
engaged in searching or in supplying missing links/documentation,
because the interface is Web-like yet requires little "markup" skills
(close to the minimum over pure text input).
I did try searching myself, of course, and found this reference to one
person's experience with such a thing, dated from last year:
[Claude Muncey]
http://c2.com/cgi/wiki?ClaudeMuncey
"I have an NT based Wiki set up at work that I am using for database
documentation, and at least one other team member has started to use
it quite skillfully for that."
So, I may be crazy, but hopefully I haven't completely lost touch!
What I would see as the value in such examples is not the technical
foundations, which could be Linux as easily as NT, but user experience
touches, e.g. custom formatting for linking on field names, "lookup"
values, SQL text, etc. Possibly the example could demonstrate that
database documentation can be done successfully with little or no such
customization. I'm open to whatever others have tried, and being
somewhat familiar with pricing guidelines, I expect only an apt link
if one exists, not a multi-page essay (unless someone volunteers!).
regards, mathtalk-ga
