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)
|
