FSD001: Documentation structure

Header

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

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 git log.

Requirements

Requirement: Document naming/numbering DOCREQ_01

status: PASS tags: docreq source: 61508 Derived: MOTIVATION_001_007 Source: EN_61508_1_5_2_7, EN_61508_1_5_2_8, EN_61508_1_5_2_10

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.

Requirement: Document header DOCREQ_02

status: PASS tags: docreq source: 61508 Derived: TEST_001_008 Source: MOTIVATION_002_018, EN_61508_1_5_2_7 Nested: 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: TEST_001_008 status: PASS Derived: RESULT_001_008 Source: DOCREQ_02 Parent: DOCREQ_02 Nested: RESULT_001_008 Verify that all documents contain the information specified in Document header (DOCREQ_02). RESULT: EN-61508-1 clause 5.2.8: company procedures/practices: RESULT_001_008 status: PASS date: 2024-12-02 verifyer: SSP Source: TEST_001_008 Parent: TEST_001_008 All documents contain a header with the specified information.

Requirement: Document version numbers DOCREQ_03

status: PASS tags: docreq source: 61508 Derived: TEST_001_009 Source: EN_61508_1_5_2_9, EN_61508_1_5_2_10 Nested: 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 TEST_001_009 status: PASS Derived: RESULT_001_009 Source: DOCREQ_03 Parent: DOCREQ_03 Nested: RESULT_001_009 Verify that all documents have version numbers. RESULT: Version numbers RESULT_001_009 status: PASS date: 2024-12-02 verifyer: SSP Source: TEST_001_009 Parent: TEST_001_009 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.

Requirement: Documentation control scheme DOCREQ_04

status: PASS tags: docreq source: 61508-1 Derived: MOTIVATION_001_010 Source: EN_61508_1_5_2_8, EN_61508_1_5_2_9, EN_61508_1_5_2_11

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.

Requirement: Documentation revision history DOCREQ_05

status: PASS tags: docreq source: 61508 Derived: MOTIVATION_001_010 Source: EN_61508_1_5_2_11

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 MOTIVATION_001_001

status: PASS Source: EN_61508_1_5_2_1 Blocked by: MOTIVATION_002_024

All lifecycle phases have corresponding FSD documentation with inputs, activities, and outputs. See Realisation phases (MOTIVATION_002_024) which documents all phases.

Motivation: Req 5.2.2 of 61508-1 MOTIVATION_001_002

status: PASS Source: EN_61508_1_5_2_2

The documentation contains sufficient information for the management of functional safety. See FSD002: Management of functional safety.

Motivation: Req 5.2.3 of 61508-1 MOTIVATION_001_003

status: PASS Source: EN_61508_1_5_2_3

The FSA is carried out with this documentation as a basis.

Motivation: Req 5.2.4 of 61508-1 MOTIVATION_001_004

status: PASS Source: EN_61508_1_5_2_4

The information documented is as stated in EN-61508-1 clause 5.2.4: do... (EN_61508_1_5_2_4). Also see motivation for element safety function Element safety function (MOTIVATION_002_001).

Motivation: EN-61508-1 clause 5.2.5: sufficient documentation availability MOTIVATION_001_005

status: PASS Source: EN_61508_1_5_2_5

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 FSD002: Management of functional safety.

Motivation: EN-61508-1 clause 5.2.6: accessible and accurate documentation MOTIVATION_001_006

status: PASS Source: EN_61508_1_5_2_6

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 MOTIVATION_001_007

status: PASS Source: DOCREQ_01

All documents follow the naming scheme specified in Document naming/numbering (DOCREQ_01).

Motivation: Documentation control scheme MOTIVATION_001_010

status: PASS Source: DOCREQ_04, DOCREQ_05

The documentation control scheme is as specified in Documentation control scheme (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 Documentation revision history (DOCREQ_05). FSD001: Documentation structure is available to all parties that have access to the documentation repository.

Revision History

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.