systems documentation standards?

[Kay]

Back in the Stone Age when I built databases in the 1980s, different clients had different standards by which they wanted their programs/databases documented. I'm talking about System documentation, not User documentation. The standards were often part of the overall development methodology adopted by the team. I am currently freelancing rather than working for consulting companies and need to know what you young chickens are using for doc standards, if anything? I must have lost all my references back in the flood. Am I talking Ancient Arabic? Anyone follow any standards these days?

Thanks ever so much, Kay.

[Kurt Knippel]

quote:

---

Originally posted by kattatonic:

Back in the Stone Age when I built databases in the 1980s, different clients had different standards by which they wanted their programs/databases documented. I'm talking about System documentation, not User documentation. The standards were often part of the overall development methodology adopted by the team. I am currently freelancing rather than working for consulting companies and need to know what you young chickens are using for doc standards, if anything? I must have lost all my references back in the flood. Am I talking Ancient Arabic? Anyone follow any standards these days?

---

I am afraid that time has erased a couple of items from the canon of systems design on anything smaller than a corporate scale. Those items being development methodologies, specifications and documentation.

Sadly most people have only the barest grasp on what they actually want or need and would rather go through 4 rounds of redevelopment, than sit down and write some specifications. Likewise no one wants to pay for someone to write documentation, not for the system and certainly not for the users. Finally the idea of development methodologies has gone away since most systems can be developed by very small teams, if not single individuals. There is no longer anyone to administer a development methodology, nor anyone to really benefit from it.

The best that I can advise in this environment is to have a set of standard files with which you start all of your projects, and choose a set of naming conventions and stick with them in your development. This is about as close to what you were inquiring about as clients today are willing to pay for.

Check out Barney Lawn's really nice standards white paper on the Core Solutions website for some good starts. I think it is www.coresolutions.on.ca

[Anatoli]

Let me ad, that I am just about to start conversion of www.coresolutions.on.ca Standards into Czech Language.

We would like to have clear starting point for multi-authoring work.

[Kurt Knippel]

quote:

---

Originally posted by Anatoli:

Let me ad, that I am just about to start conversion of

www.coresolutions.on.ca

Standards into Czech Language.

We would like to have clear starting point for multi-authoring work.

---

Since this is a copywritten work, I would make sure that you check with Barney first. He has some legal reasons against people making changes, but he might be interested in this effort and may be able to give you some assistance. He is a really nice guy and I am sure would be willing to give the project consideration with either a phone call or e-mail contact.

[Kay]

Thank you Kurt, and thanks Barney.

WARNING: RANT AHEAD

I lament. Boo hoo. Believe it or not, I have a client who has asked me to document several huge systems. They lost their FMP primary programmer - he ran away and left several years of business-dependent systems behind undocumented. Of course they need upgrading. Of course no one knows what they do between input and output. Thus the desire for systems documentation. So I asked their boys (who will be doing the upgrading), what they'd like, do they use a standard, are there any examples kicking around so I can produce something functional for them? "No, nada, zip, duh we don't know." These guys have built some wonderful things but don't customarily upgrade or maintain. I never thought I'd miss specs etc. None of these ever produced either of course. No starting point. Blah blah blah whine whine whine.

Anyway, I truly appreciate your answer. I don't shoot messengers. I guess my answer is to see if Barney's stuff will help, and document things the way I wish someone would document ahead of me when I have to take over someone else's work.

Kurt, you miss these things a titch, don't you? I can tell. Just a little.

Thanks as always for your help, Kay.

[Vaughan]

Criteria for documentation:

Not IsEmpty(documentation)

Hey, in my (limited) experience, even crappy documentation is better than none. And in my (limited) experience the documentation takes as long or longer than the system development.

I'd be tempted to tell them that it'd be cheaper to get a replacement database developed (and documented as it was being built) than to reverse-engineer and document an existing system.

[Chuck]

Just to put my two cents worth in here, I include the developer documentation throughout the system as it's being built. I make liberal use of the Comment script step, using it before just about every script step to make sure that what is going on is understood. In addition, I categorize my scripts by function (such as Developer, Navigation, Search, etc.) and keep the list of scripts in a very specific order using empty scripts named "-" to separate scripts.

I document relationships by using a very specific naming convention:

FileName~LocalField#ForeignField

Since in addition to relationships necessary for any system (such as a relationship between clients and invoices) I also make use of programming relationships (such as a relationship to show the data from the currently selected portal or a relationship to create a new related record from the current record) I often have dozens of relationships, which I also keep separated by function. Since relationships can't have names that are the same (unlike scripts) I use dashes to separate the relationship sets, such as "-" for the first separation, "--" for the second, etc.

For fields, I also comment often, but since fields don't have built-in commenting, when I feel that a field needs a comment, I'll create a calculation field with a text result that is unstored called Field_Comment and enter the comment in there as text in quotes. Fields are also separated by function (i.e., Standard_Fields, File_Specific_Fields, File_Specific_Developer_Fields, etc.). These sets are separated by global fields with names like a____________, b____________, etc.

I also always have a developer layout where I can put other notes about the system. I just enter this as text on the layout rather than use a field. I usually only use this layout for documentation in the main menu file.

I haven't really found a good way to document value lists, but I also haven't found a great need to, since they are usually self-explanatory by looking at the value list definition.

Hope this helps others.

Chuck

[Anatoli]

quote:

---

Originally posted by CaptKurt:

Since this is a copywritten work, I would make sure that you check with Barney first. He has some legal reasons against people making changes, but he might be interested in this effort and may be able to give you some assistance. He is a really nice guy and I am sure would be willing to give the project consideration with either a phone call or e-mail contact.

---

I did that through e-mail. I am in it not for the money. It will be hell lot of work, but we must start somewhere. It is about time to connect skilled people and for that we need standards.

[Kay]

These are some very valuable ideas Chuck. Thank you so much. I actually missed your post at the time of writing but came across it today looking for something else.

[ August 07, 2001: Message edited by: kattatonic ]

[LiveOak]

1980's the stone age, ouch! How about software development in the 1960's... .

There are a few established standards used by the military. I've not looked at a current version, but there is MIL-STD-2167, probably available from the government printing office (or a friend in aerospace). It included such items as Requirements Specifications, Design Specificatons, and Unit Development Folders, etc. Might be worth a look in the new century. Now back to my rocking chair...

-bd

[Kurt Knippel]

quote:

---

Originally posted by Chuck:

For fields, I also comment often, but since fields don't have built-in commenting, when I feel that a field needs a comment, I'll create a calculation field with a text result that is unstored called Field_Comment and enter the comment in there as text in quotes. Fields are also separated by function (i.e., Standard_Fields, File_Specific_Fields, File_Specific_Developer_Fields, etc.). These sets are separated by global fields with names like a____________, b____________, etc.

---

Personally, I do not care for this kind of field documentation for the simple reason that it relies on a very specific placement of fields to convey thier meaning. As soon as you want to sort by type or creation date you lose most of that meaning.

I use a bracketed description abbreviation to denote the field descriptions. This way I get the fields grouped properly when I sort by Name, but I keep all of my categorization when sorting by other criteria as well.

NormalUserDataField

[calc] CalculationField

[dev] DeveloperField - used for various housekeeping purposes.

[disp] DisplayField - usually a calculation.

[key] KeyField

[sum] SummaryField

_GlobalField

and so on. This way all Globals are kept together (at the end), and all user fields are at the beginning. Obviously I have a whole slew of little description abbreviations, but you get the point.