Why documentation is often skipped
Developers skip documentation under time pressure, intending to “do it later.” Later never comes. Six months later, when someone else needs to modify the integration, they’re starting from scratch — recreating understanding that should have been captured.
Good documentation is a professional discipline, not optional overhead.
Integration specification template
For each OIC integration, document:
## Integration: [INTEGRATION_NAME]
**Version**: 1.0.0
**Type**: Scheduled / REST trigger / Event
**Owner**: [Developer Name]
**Last Updated**: [Date]
### Purpose
[One paragraph describing what this integration does and why]
### Trigger
[Trigger type, schedule, or calling system]
### Source System
- System: [Name]
- Connection: [OIC connection name]
- Data extracted: [Key fields]
- Filter/selection criteria: [How records are selected]
### Target System
- System: [Name]
- Operation: [Create/Update/Delete]
- Mapping summary: [Source field → Target field for key fields]
### Error Handling
- On REST failure: [retry count, delay, notification email]
- On validation failure: [log to table / skip / abort]
- On success: [post-processing, notification]
### Dependencies
- Upstream: [What must complete before this runs]
- Downstream: [What this feeds into]
### Known Limitations
[Any edge cases, known issues, or constraints]
VBCS application documentation
Document:
- User roles and permissions matrix
- Page/flow inventory with purpose of each
- Service connections and which OIC integration each calls
- Business object list with field descriptions
- Known limitations and workarounds
SQL/PL/SQL documentation
Every stored procedure should have a header comment:
/**
* PROCEDURE: create_po_approval_workflow
* PURPOSE: Initiates the PO approval workflow for a given PO.
* PARAMS:
* p_po_id IN NUMBER - PO header ID
* p_result OUT VARCHAR2 - 'SUCCESS' or error message
* NOTES:
* Called by OIC integration POAPPROVAL_TRIGGER_01.
* Requires row in po_workflow_config for the PO's BU.
* HISTORY:
* 2026-01-15 AJ Created
* 2026-03-01 AJ Added multi-currency support
*/
Storing and sharing documentation
Use a team wiki (Confluence, Notion, or SharePoint) with a consistent folder structure mirroring your Git repository. Documentation that lives only in someone’s head or on a local drive is no documentation at all.