Forum .LRN Q&A: Re: Assessment items discussion thread

Malte, I've uploaded all the OG files from which I exported the subsystem graphics. You'll see them in the listing of the Assessment files in the file storage each with the same name as the graphic image appended with the term OmniGraffle. It should be clear.

I've also included a link to the OG file just above the image in each page, so that should make it easier to download the OG files for editing. Hopefully the naming scheme will make it easy to upload new versions into the correct place.

There are a variety of other files in our repository used in the older doc pages. They kinda clutter up the area but I don't think it's bad enough to move them into subfolders, and I don't want to bother with reediting all those archival pages.

Re the level of detail to put into the diagrams (like FKs etc) -- I didn't find an obvious way to make OG do some of the formatting that a tool like Lars et al. use in their Simulation package (/contrib/packages/simulation) can do. If anyone knows how to do this and wants to bother, that's fine.

But personally I think that kind of detail is better kept in the "Specific Entities" section where we list and discuss the design. The purpose of the graphics is to draw the Big Picture and keep things in perspective. Trying to maintain All The Details in *two* places (the listings *and* the graphics) makes it likely that *neither* place will have the reliable information.

Even the way we have the graphics now invites errors during edits, since we have the "master graphic" (which I started off considering the Authoritative Schema) and all the subsystem graphics. If anyone edits the latter, I would think they should make the same edits to the former. But that doesn't seem all that likely, does it? So there is a high risk of Graphic Slippage. 😉

Anyway, I suggest that we follow this convention:

1. The Definitive Design Spec for any entity is its listing/discussion in the "Specific Entities" section of its subsystem.
2. The Most Reliable Graphic for any entity is the subsystem graphic on the page on which that entity's "Specific Entities" discussion occurs.
3. The Master Schema Graphic is *not* the definitive documentation of anything, though everyone who edits stuff here should make a good faith effort to keep it accurate and up to date.

So, how much SQL detail do we need to write in these html pages? Seems to me that we don't need a lot more; the primary keys and foreign keys are pretty obvious just by their naming scheme. I don't think that we need to type all the constraints etc here; we'll just have to do it again when we crank up emacs and start writing *.sql files. If anyone has a strong opinion about something like whether an attribute needs to be a varchar(100) and not a varchar(200), that's the kind of thing that *should* be stated in the "Specific Entities" discussion, but the *rationale* is more important to type in than the exact SQL syntax.

At least that's the way I like to approach development docs. 😉