Documentation

Summary

This project document developer checklist should be used by all Synetec developers to ensure we maintain high-quality documentation throughout the project lifecycle. Our aim is to ensure maximum maintainability of the code we produce.

Project start

All projects

We will document:

• Any necessary steps – including the repos and database/storage/tools required – to get the project up and running in a local development environment
• Any agreed variation with the client from our coding standards (and static analysis rules)
• The pipelines used for deploying code to any existing test, UAT and production environments if these will be retained for our work (see Build and deployment below)
• Any differences between test, UAT and production environments
• The sign-off procedure for UAT and production releases including any restrictions.

Working with an existing codebase

When we work with code created elsewhere, we will also:

• Capture any existing documentation for the system (see Existing documentation below)
• Run static code analysis on the repos and document bugs, security issues and code smells with the existing code
• Document the current code coverage by automated tests.

Project documentation

The discovery process will capture the high-level requirements for the project. This will be documented across Microsoft Office documents and one or more Miro boards.

This will be translated into Epics, Features and Stories usually in Azure Dev Ops or Jira along with the agreed acceptance criteria for each. These will be managed by the Product Owner.

Specific processes, business logic and implementation information will be captured in the project wiki.

Code documentation

We aim for our code to be self-documented whenever possible. This is managed by independent assessment of pull-requests.

Pull request checklist:

• It complies with our coding standards – especially naming conventions and single-responsibility principle.
• Unit tests are in-place and named appropriately to understand what the test is.
• All public classes and methods using code comments to document the purpose (classes and methods), parameters (method) and return object (method).
• Commits and pull requests are linked to the Feature, Story or Task (creating a link back to the requirements from the code).

End of sprint

At the end of a sprint the team should check that:

• All features are linked to the code which delivers them
• The processes and business logic in the project wiki reflect any changes made in the sprint.

Existing documentation

The following is a checklist of documentation which we seek when working with pre-existing code:

• Design & Architecture Documentation with any updates made to the systems design
• Any API Documentation
• Code/App Structure Documentation
• Requirement Documentation (Business and System)
• Entity Relationship Documentation
• User Admin Documentation (roles, groups, access, etc.)
• Component & Integration Documentation
• User and Help Documentation
• Front end design documentation
• Test Cases / Test Results
• Change Requests for system functionality or design changes

Build and deployment

Information to capture:

• Hosting environment: Azure, AWS, etc
• Type of hosts: App Service, Functions, Docker, VM, etc
• Build tool and pre-requisites
• Credentials required (actual credentials should not be recorded or stored in any insecure format)
• Database deployment requirements.

Documentation locations

Individual clients may request changes to these, but normally documentation will be found:

• SharePoint Team site for the project
  • Discovery documentation
  • Any generic development documentation which applies to all projects for the location
• Azure Dev Ops/Jira
  • Epics, Features and Stories
  • Test cases
  • Project specific development documentation
• Azure Dev Ops/Github
  • Code repositories
• Miro
  • High-level architecture diagrams
  • Entity relationship diagrams
  • Wireframes