I’m developing a software documentation in a project, and much of it are just CRUD or CRUD based functions. As you can imagine, a lot of the rules are constraints about fields validation, things like length, range, data type and masks of the field.
Writing all those rules would be cumbersome to write and to read, so I’m wondering, what are the option available to include such rules in a software documentation, in a way that it is not tedious to write/read it all?
Edit – Clarification
The rules and being taken from an old desktop legacy application, and we are going to document the current validations, features and forms; so the application will be implemented in a more up-to-date (web) platform, considering usability and consistency in the new system. The documentation is handwritten using the Sybase PowerDesigner tool, but the document can be written in doc inside the tool.
Some of it are cross-field validation rules, for example;
- For a person of type X, residing on country Y, the value of field A must be validated using the B rule.
- For a person of type X, residing on country Z, the value of field A must be validated using the C rule, and the field D, validated through E rule.
Type X, country Y, field A, field D, etc, are all values extracted from fields on the forms.
2
So you have an old legacy application at hand which contains already all the rules you are going to document, and you are looking for a way to somehow “extract” some of the rules out of it, without writing them down manually.
Actually, if that is possible depends completely on the technology and architecture of that application. You did not tell us anything about those things, so I can give you only some very general advice.
The key factor here is how much meta data the sources of the old legacy system contain. By “meta data” I mean any kind of machine readable, self-describing information. If there is some metadata, you can use it as input for some kind of doc generator you will have to write.
For example, if the legacy application is database-founded, there is a good place to start with. Almost any serious database allows the extraction of table names, attribute names, attribute data types, db constraints etc. in a programmatic way. So either you write yourself a program which extracts those information out of the DB, or you use the reverse engineering capabilities of PowerDesigner which allow you to generate a complete ER model within minutes.
If the application is not database founded, or the validation rules are not implemented as database constraints, the task is typically getting harder. Does the old technology used allow to determine which forms are available? Does it allow to extract which attributes are on each form, and was there a standard way to add validation rules by configuration instead of coding? Learn enough about the old technology to answer that kind of questions. Then you may have a chance to save some manual documentation work.
However, features and validation rules of the old legacy application which are buried in some pile of hand-written code can almost never be extracted automatically. Don’t expect any “magic bullet” to to solve this problem for you – there is none, this part of the docs you will have to write manually. Find out about the rules either by reading the existing docs of the old application, by reading/debugging the source code of that application or by try-and-error using the application.
EDIT: you asked for a way to avoid tedious writing work as well as tedious reading. My answer above was how to avoid tedious writing. And I guess the reading of such validation rules will be always a little bit tedious, independently of the form you choose.
However, if there is no existing meta data available, it may be good idea to create such metadata during your documentation process, for example, within your PowerDesigner models. PowerDesigner is tool where AFAIK you can store all model data in a central repository. Due to the manual, it has scripting capabilitities (it seems to have a COM API which can can be accessed by any COM capable programming language from outside) and it may also be possible to extend the PowerDesigner meta model to your needs. So instead of writing all your validation rules into separate documents in a verbal form, learn enough about your PowerDesigner tool that you can store that information in a machine-readable form there. Then develop a doc generator using the inbuild scripting capabilities or the COM API.
This way, you can keep the documentation source very compact, without much redundancy. The generated docs will have 100% consistent layout, and if needed they can be easily tailored for different purposes. If the “readers” of the docs don’t like the form, just change the generator and regenerate the docs again.
Of course, this effort only pays for applications of a certain size. I have done something similar in the past for two different CASE tools, and in reality it is easier than it may sound at a first glance.
3
The best to make this readable is to keep the layout of these requirements consistent across the Doc.
I think that is more important that the format itself, that being said i would use a basic grid. If no value is needed, leave it Blank. (as opposed to writing None)
Column One is Filed Property, Column 2 is that value (or description).
Name Email
Type Text
Length 150
FK Constraint
Other Validation Standard Email Validation