Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

I was tasked to document our stored procedures.

  • Target audience: Technical
  • Purpose: To have a good documentation in preparation for migration.

I'm assuming someone has already done it.

share|improve this question
    
All the "Why do we do it like this?" questions along with their answers. I.e. try to capture the design phase. –  user1249 Sep 4 '12 at 8:06
add comment

1 Answer 1

up vote 9 down vote accepted

At a minimum, you document it like you would a function or method in source code. For example:

  • What does the stored procedure do? Does it update or modify any tables or just read values?
  • What are the arguments? What are their allowed values? Can they be NULL?
  • What is returned? Is it a scalar value? Is it a table? If so, what are the fields and what do their values mean? Is there a single row or multiple rows?
  • Give an example of its use
  • Are there related or similar stored procedures? For example, is it normally used in conjunction with another stored procedure?

Depending on your environment, the following may or may not apply:

  • Should it be called within a transaction or not?
  • Are there any special security requirements? For example, does the caller need access to particular tables?
  • Are there any known bugs that are not fixed due to backwards compatibility reasons?
  • Does this stored procedure supersede other stored procedures? Is it obsolete or deprecated?
  • Is the stored procedure written by hand or auto generated? If it is auto generated, what tool generated it?
  • Does the procedure deal with sensitive information like credit card details, hashed passwords or Personally Identifiable Information (PII)?

For the actual documentation, the best experience I had was using a Wiki. Each stored proc had its own page and so the documentation was versioned independently with an easily accessible history and change list. Users could subscribe to changes via E-mail and the documentation was always in an easily accessible location.

share|improve this answer
    
Great inputs akton. How would you manage document revisions? Do you store the document in a revision control system? Or do you keep a table of changes in the document itself? –  Joset Sep 4 '12 at 1:54
    
@Joset I added paragraph to the answer talking about Wiki use. –  akton Sep 4 '12 at 1:59
    
I appreciate all your inputs. –  Joset Sep 4 '12 at 2:12
    
You might want to add: If a resultset is returned, is it a single row or multiple rows? –  jmoreno Sep 4 '12 at 7:49
    
@jmoreno Good idea. I have updated the text. –  akton Sep 4 '12 at 7:55
add comment

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

Not the answer you're looking for? Browse other questions tagged or ask your own question.