IRAD Documentation Guidelines

Documentation Guidelines

The following are some guidelines for writing documentation. Not every item will apply to every project. The goal is to create documents that are consistent, understandable, and up-to-date.

Project History/Origin

• Major players
• What was in use before
• Problems this project was supposed to address
• Include any proposals given to end users
• Major updates, server migrations? (for doc updates)

End User Documentation

Data:

• Hosting of live/test data (server, instance, schema, accounts)
• Data model
• Data description
• Business Rules (if not trivial)
• Refresh schedule (if applicable)
• Data maintenance (any manual jobs, interventions)

Code inventory:

• Include servers, directory paths
• Include web servers, account names, test environment
• Include main code and any additional cron jobs, pl/sql, web code, etc
• Any special libraries used
• Updating live code, compiling instructions
• Any special testing required/suggested
  
  Code summary:
  
  For each program listed in code inventory --
• Overview of code
• Design philosophy
• Relationship map between code/data objects
  
  Authorization/Security Policy:
• How is authorization handled in the code
• How is authorization requested/maintained
• Define the different access levels
• Does authorization expire automatically?
• What auditing/logging is kept
  
  Privacy Policy:
• What sensitive data is maintained
• Who has access to everything, who has partitioned access
• Disclosures to end users (remind users of confidential data)