Documentation is a description of what has been implemented based on the design and architectural requirements.
- Documentation answers ‘how’ something has been designed/architected/implemented without necessarily addressing the ‘why’ and the design/requirement goals
- Documentation is typically in the form of Readme files in the Github repository describing individual contract functionality combined with functional NatSpec and individual code comments.
- Documentation in many cases serves as a substitute for specification and provides critical insights into the assumptions, requirements and goals of the project team
- Understanding the documentation before looking at the code helps auditors save time in inferring the architecture of the project, contract interactions, program constraints, asset flow, actors, threat model and risk mitigation measures
- Mismatches between the documentation and the code could indicate stale/poor documentation, software defects or security vulnerabilities
- Auditors are expected to encourage the project team to document thoroughly so that they do not need to waste their time inferring this by reading code
- What/How
- Architect/Implement
- README/Comments
- Assumptions/Shortcomings
- Infer: Lost Time