Structure: Too many top level chapters
(section numbers referring to V1.15)
The amount of top level chapters makes it difficult for the reader to navigate the document and to locate details.
Sections regarding similar/same topics should be in one chapter. Chapters / sections / subsections should be arranged in order of increasing detail. This will also help stakeholders to identify topics they care about more easily (eg internal implementation vs public interface).
A first suggestion is to have 5 chapters:
- Introduction
- Chapters 1. till 4. are introduction. They mention requirements from OP / Controls, but how those requirements are realized is only detailed in later sections.
- General Software requirements / recommendations
-
- Internal Software Design Recommendations
-
- Class Relationships
-
- Documentation
-
- Source Code Repository
-
- General Naming Convention
- Naming Conventions found in 6.1 are important enough to get a separate chapter
- Properties
- most other sections fit here (see also #8)
- Status / Error Reporting
-
- Conditions
-
- Logging System
-
- Alarm System
-