.. _fsd001: FSD001: Documentation structure ############################### .. header .. list-table:: Header :header-rows: 0 * - Title - FSD001: Documentation structure * - Current version - V3 * - Products - Safety Simplifier * - Requirements - 61508-1:5.2.1 to 5.2.11 (documentation requirements) * - Purpose - Specify more detailed requirements for documentation, and explain how those requirements are met. Table of contents ***************** .. contents:: Description ************* The example documentation in 61508-1, table A.2 and table A.3 is applied (with minor exceptions). QMSDOC-1761341735-17 Control of documents (available in SSP North Quality Management System) describes the SSP North AB overall routine for control of documentation. FSD001 describes additional details for FSD documentation. The document FSD303 Techniques and measures describes all deviations from the techniques and measures recommended in 61508-2, table A.16-A.18 and B.1-B.5, and 61508-3, table A.1-A.10. The structure of this document can be used as a template/guideline for other documents. The documentation tool Sphinx is used to generate documentation. This tool can automatically generate html and pdf files from source documents in restructured text. The Sphinx extension "Sphinx-needs" is used to specify requirements and track the relationships between them. Documentation consists of regular documents (mainly .rst, but also .pdf, .docx, .xls, etc.) and automatically generated reports. Documentation files are stored in a git-repository for version control. Git attaches the date, author name and email to every commit, which gives complete traceability of all changes to the documentation. Detailed revision history with author and date can be generated for each document using :code:`git log`. Requirements ************ .. req:: Document naming/numbering :id: DOCREQ_01 :source: 61508 :tags: docreq :derived: MOTIVATION_001_007 FSA documents shall have unique numbers for sorting and referencing, following this naming convention: FSDXXX-Title.docx (or other file ending, such as .rst, .xls, etc), where XXX is a unique number in 001-999. .. note:: In general, higher numbers indicate more detailed/low level documentation. .. req:: Document header :id: DOCREQ_02 :source: 61508 :tags: docreq :derived: TEST_001_008 All FSD documents shall specify the following in the beginning of the document: * title, * version, * related products (specify with model numbers), * reference to concerned requirements in 61508 or other standards, * the purpose of the document, * and lifecycle inputs/outputs if applicable. .. test:: EN-61508-1 clause 5.2.8: company procedures/practices: :id: TEST_001_008 :derived: RESULT_001_008 Verify that all documents contain the information specified in :need:`DOCREQ_02`. .. result:: EN-61508-1 clause 5.2.8: company procedures/practices: :id: RESULT_001_008 :verifyer: SSP :status: PASS :date: 2024-12-02 All documents contain a header with the specified information. .. req:: Document version numbers :id: DOCREQ_03 :source: 61508 :tags: docreq :derived: TEST_001_009 * All documents shall have a revision history starting with V1 initial version. * The version number shall be increased when released if the document was changed since the last release. .. test:: Version numbers :id: TEST_001_009 :derived: RESULT_001_009 Verify that all documents have version numbers. .. result:: Version numbers :id: RESULT_001_009 :verifyer: SSP :status: PASS :date: 2024-12-02 All documents have revision numbers and high level revision history. All documents are also checked into Git, which provides detailed version control, and keeps track of who made changes and when. The git commit hash can be used to trace back to the exact version of a document. .. req:: Documentation control scheme :id: DOCREQ_04 :source: 61508-1 :tags: docreq :derived: MOTIVATION_001_010 All documentation shall be checked into a git repository containing all relevant documentation. The main branch shall contain the latest released version of all documentation. .. req:: Documentation revision history :id: DOCREQ_05 :source: 61508 :tags: docreq :derived: MOTIVATION_001_010 Every relevant/important change of a document shall be documented in the git commit message of that change. .. note:: For example, changing the order of requirements or fixing spelling/grammar issues does not have to be documented. However, a change of the meaning or content of a requirement must be documented in the commit message. Motivations ************ .. motivation:: Req 5.2.1 of 61508-1 :id: MOTIVATION_001_001 :blockers: MOTIVATION_002_024 All lifecycle phases have corresponding FSD documentation with inputs, activities, and outputs. See :need:`MOTIVATION_002_024` which documents all phases. .. motivation:: Req 5.2.2 of 61508-1 :id: MOTIVATION_001_002 :status: PASS The documentation contains sufficient information for the management of functional safety. See :ref:`FSD002`. .. motivation:: Req 5.2.3 of 61508-1 :id: MOTIVATION_001_003 :status: PASS The FSA is carried out with this documentation as a basis. .. motivation:: Req 5.2.4 of 61508-1 :id: MOTIVATION_001_004 :status: PASS The information documented is as stated in :need:`EN_61508_1_5_2_4`. Also see motivation for element safety function :need:`MOTIVATION_002_001`. .. motivation:: EN-61508-1 clause 5.2.5: sufficient documentation availability :id: MOTIVATION_001_005 :status: PASS The FS documentation is available to all parties via Git and other QMS documentation via Sharepoint. More details about availability, parties, QMS, are specified in :ref:`fsd002`. .. motivation:: EN-61508-1 clause 5.2.6: accessible and accurate documentation :id: MOTIVATION_001_006 :status: PASS The documentation is written according to the requirements specified in 61508, and is written with the goal to be understandable for the people involved in the management, development, and FSA. .. motivation:: EN-61508-1 clause 5.2.7: document titles/index :id: MOTIVATION_001_007 :status: PASS All documents follow the naming scheme specified in :need:`DOCREQ_01`. .. motivation:: Documentation control scheme :id: MOTIVATION_001_010 :status: PASS The documentation control scheme is as specified in :need:`DOCREQ_04`. All people, before getting access to make changes to the documentation, have been instructed how to use the documentation control scheme, and most importantly how to write correct git commit messages to follow :need:`DOCREQ_05`. :ref:`fsd001` is available to all parties that have access to the documentation repository. Revision History *********************** .. list-table:: :header-rows: 1 * - Date - By - Version - Description * - 2023-08-15 - William Forsdal - V1 - Initial version * - 2024-12-02 - William Forsdal - V2 - Added tests for requirements. * - 2025-01-30 - William Forsdal - V3 - Clarified motivations, updated statuses.