5.2.2. Guideline for Detailed Design documentation¶
In order to develop correctly a software module, it is required to first write down a detailed design document which will guide you to develop correctly your module. Indeed, beginning with a design document will force you to think about:
- What your SW module shall do
- What are its dependencies
- What will be its structure
- How it will do its functions.
Once these steps are down, it will make things easier to specify your APIs and then develop them.
Such document generally contains requirements traceability in order to make sure that high level requirements are correctly fulfilled. In our case, we don't have input requirements for the moment, but this is the next evolution planned for the project (2019.03.27).
Also, in order to guide you with the content of this document, you need to think as a "tester" in order for him to know what he needs to test in order to make sure that the implementation of your module is correct. Indeed, based on this detailed design document, both software implementation AND software unit tests will be developed, ideally by 2 different persons.
These steps are based on the V Cycle development process:
Below is an example of sections which can/shall be present in the detailed specification of a driver. It is based on the automotive standard "AUTOSAR" which defines, among lot of other documents, low level driver specification, like a CAN driver: AUTOSAR_SWS_CANDriver.pdf. All the AUTOSAR specification can be found here if needed: https://www.autosar.org/standards/classic-platform/
The goal is not to write text for fun but to provide enough information for other to understand how is developed your module, what it contains and why you chose to make the choice you made. Indeed, some functionalities can be implemented in various ways, but some are most probably more adapted to your case so please indicate the reasons of your choice.
Below is the detailed design document' structure. A dedicated documentation page is provided as template: simply copy its content and paste it in a new page when creating a new modules's detailed design.
- General description of the driver and of the dedicated chip (including link to datasheet, best if attached directly in the documentation page)
- Acronyms and abbreviations
Constraints and assumptions
Limitations: Functionalities of the chip which are not supported by the driver
- Assumptions: describe if assumptions were made when developing the driver (unclear specification, etc.)
Dependencies to other modules: Indicates the API, structure or types defined in other modules and which are necessary in this driver
- File Structure
- Driver State Machine
- Development errors (if applicable)
- Function definitions
- Call-back notifications
- Scheduled functions
- Sequence diagrams
- Configuration specification