| Issue Number | 3291 |
|---|---|
| Summary | [EBMS/CiteMS] Technical documentation |
| Created | 2011-01-06 16:11:49 |
| Issue Type | Improvement |
| Submitted By | alan |
| Assigned To | alan |
| Status | Closed |
| Resolved | 2013-07-11 21:31:43 |
| Resolution | Fixed |
| Path | /home/bkline/backups/jira/ocecdr/issue.107619 |
BZISSUE::4981
BZDATETIME::2011-01-06 16:11:49
BZCREATOR::Alan Meyer
BZASSIGNEE::Alan Meyer
BZQACONTACT::Margaret Beckwith
There is currently no technical documentation for the Citation Management System. We have a good user manual that explains what the system does and what users have to do to operate it, but there is no documentation on the system design, the database design, or the implementation.
The lack of documentation is a problem for current maintenance. Fixing bugs or correcting errors in the database is often risky because none of the current programmers know very much about how the system works inside. It's possible to break something else in an attempted fix.
Documentation will also be useful if and when we replace the system. It will educate the programmers about what works well and what works poorly in the existing system so that we can apply the lessons in a future system. It will also give us some indispensable understanding of the data so that we can correctly export the existing data and convert and import it into a new system.
This task is to produce technical documentation for the CiteMS, with highest priority given to documenting the database.
BZDATETIME::2011-01-06 16:57:53
BZCOMMENTOR::Cynthia Boggess
BZCOMMENT::1
I think this is a great idea. I wrote the user manual and assumed that Pete Chauvette, the CMS developer, was handling all the technical documentation. We should probably contact Pete to see if he still has any sort of technical documentation or anything that could be used to document the database...or at least where to look. Someone may have already asked him about this when the CMS was recently transitioned to NCI. William may know more about this.
BZDATETIME::2011-01-06 17:41:48
BZCOMMENTOR::Alan Meyer
BZCOMMENT::2
(In reply to comment #1)
> ... We should probably contact Pete to see if he still has
any
> sort of technical documentation or anything that could be
used
> to document the database...or at least where to look. Someone
> may have already asked him about this when the CMS was
recently
> transitioned to NCI. William may know more about this.
We did ask in the past. It might not hurt for someone who knows
Pete, Lijuan, or anyone else who worked on the system, to try
again with each of them.
BZDATETIME::2011-01-11 12:01:34
BZCOMMENTOR::William Osei-Poku
BZCOMMENT::3
(In reply to comment #2)
> (In reply to comment #1)
>
> > ... We should probably contact Pete to see if he still has
any
> > sort of technical documentation or anything that could be
used
> > to document the database...or at least where to look.
Someone
> > may have already asked him about this when the CMS was
recently
> > transitioned to NCI. William may know more about this.
>
> We did ask in the past. It might not hurt for someone who
knows
> Pete, Lijuan, or anyone else who worked on the system, to try
> again with each of them.
That is right. We asked for a technical documentation but there was none so Pete had to create a new Data Dictionary. He also included a database create script. Please see Bug# 4521. They are in there as attachments.
BZDATETIME::2011-01-11 17:51:49
BZCOMMENTOR::Alan Meyer
BZCOMMENT::4
(In reply to comment #3)
> (In reply to comment #2)
> > (In reply to comment #1)
> >
> > > ... We should probably contact Pete to see if he still
has any
> > > sort of technical documentation or anything that could be
used
> > > to document the database...or at least where to look.
Someone
> > > may have already asked him about this when the CMS was
recently
> > > transitioned to NCI. William may know more about
this.
> >
> > We did ask in the past. It might not hurt for someone who
knows
> > Pete, Lijuan, or anyone else who worked on the system, to
try
> > again with each of them.
>
> That is right. We asked for a technical documentation but there was
none so
> Pete had to create a new Data Dictionary. He also included a
database create
> script. Please see Bug# 4521. They are in there as attachments.
Thanks.
I just looked at these.
The "script" is just an auto-generated output from SQL Server. I made one of those myself.
The "data dictionary" is pretty skeletal, but it looks useful. I hadn't seen it before. Thanks for calling it to my attention.
BZDATETIME::2011-02-14 19:02:00
BZCOMMENTOR::Alan Meyer
BZCOMMENT::5
This is my revision of the Excel format data dictionary provided by Pete Chauvette, one of the technical staff on the original system. The original from Pete is available here:
http://verdi.nci.nih.gov/tracker/attachment.cgi?id=1748
I have gone through all of the listed tables and examined actual data in our system, performing queries to see how data is related, how well controlled it is, how common certain values are, whether there are one to one, one to many, or many to one relationships, whether data is original or denormalized, and so on. In some cases I've also searched the source code to see if I could find out how some of the data is used.
The results of my research went into this revised version of the spreadsheet. My goal is to provide documentation to help us in any future maintenance we do on the existing system, in designing a new system, and in converting data from the existing system to load into a new one.
Attachment CiteMgtSys_DataDictionary.xlsx has been added with description: CiteMS data dictionary as an Excel spreadsheet
BZDATETIME::2011-12-20 10:22:56
BZCOMMENTOR::Alan Meyer
BZCOMMENT::6
This is an updated version with additional information added by me.
Attachment CiteMgtSys_DataDictionary.xlsx has been added with description: CiteMS data dictionary as an Excel spreadsheet
BZDATETIME::2011-12-22 09:50:17
BZCOMMENTOR::Bob Kline
BZCOMMENT::7
Attachment legacy-citems.pdf has been added with description: legacy table relationships
This issue was for documentation of the old Visual Basic / ASP Citation Management System. The documentation we have is as complete as is worth making it and may not be used again.
| File Name | Posted | User |
|---|---|---|
| CiteMgtSys_DataDictionary.xlsx | 2011-12-20 10:22:56 | |
| CiteMgtSys_DataDictionary.xlsx | 2011-02-14 19:02:00 | |
| legacy-citems.pdf | 2011-12-22 09:50:17 |
Elapsed: 0:00:00.001465