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)