Skip to main content

Document Structures for Product Development

This guideline outlines how to organize and manage product and project documents during development and maintenance. It applies only to internal R&D documents at the product and project level, not for publication through the ABB Library or other channels.

Intended for​

Release owners, quality control managers, developers, and configuration managers.

Purpose and scope​

The aim is to keep all product and project documents in one place, making them easy to find and ensuring everyone knows where to store and locate them. This proposed structure can be used across product lines, and each product or stream can adapt it to suit its specific needs. For existing products with well-established folder structures, it's okay to continue using them if they work well.

This proposed folder structure can be applied to either a document management system or a tool chosen by product line or stream for archiving technical or project planning documents.

Formal controlled documents​

All formal controlled documents recommended be archived in the designated Document Management System (DMS) or approved tool. For detailed document types and responsibilities, refer to 3BSE039313 Names on RACI or "Artifacts" under respective process. More information on formal document review and approval handling is available in Document Management guide.

Requirements on formal control​

  • Version control (with clear revision history)
  • Formal review and approval (per applicable standards/regulations)
  • Strict access and retention policies

Examples of Formal Documents​

  • Requirements specifications
  • Design documents (architecture, schematics .etc)
  • Test documentation:
    • Test plans
    • Protocols
    • Reports
  • Risk assessments(according to regulations/standards, e.g.,safety,Security,Ex):
    • FMEA/FMECA
    • Threat analyses
    • Mitigation plans
  • Compliance & Regulatory records:
    • Regulatory submissions(e.g., CE Technical files)
    • Audit trails(change logs, review histories)
    • Certifications
  • Project & Governance
    • Project artifacts(scope,deliverables,team,plans)
    • Milestone reviews
    • Gate reports

Note: Informal drafts, temporary working files, or documents managed in other tools (e.g., Azuredevops) are excluded from DMS archiving unless they become formal deliverables.

Documents should be organized by their respective system and product version to streamline maintenance throughout the product lifecycle. In the current DMS, that is, under ATPA, the different system products are located under the folder Mig_10_Operations > 04 Product Development and Release, and each product is located within the "System" folder. This guideline focuses on documents managed at the product level.

For visual reference, see the extracts of the system families structure for OnePCP DMS:

00_system_families_structure.png

And the 800xA system family structure is below:

00_800xA_family.png

Below each product, there are three to four folders:

  • 01 Technical Documents (Product life cycle)

  • 02 Projects Documents (Project life cycle)

  • 03 Product Life Cycle (Non-technical)

  • 04 Process Related Guidelines (optional, can be used for product line detailed instructions and guidelines)

The first release of a project should create the following structure under the new product name:

  • 01 Technical Documents (Product life cycle)
  • 02 Projects Documents (Project life cycle)
    • Release 1.0
  • 03 Product Life Cycle (Non-technical)
    • Release 1.0

And every release after the first would then add as below:

  • 01 Technical Documents (Product life cycle)
  • 02 Projects Documents (Project life cycle)

    • Release 1.0

    • Release 2.0

    • ......

  • 03 Product Life Cycle (Non-technical)

    • Release 1.0

    • Release 2.0

    • ......

Technical documents (Product life cycle) structure​

The 01 Technical Documents folder contains all documents that describe the product from a technical perspective and remain valid throughout the product lifecycle until they become obsolete. Documents like descriptions of functions and design descriptions are typically updated for new releases, i.e., one unique ID with new revisions, while others, such as test records, are created new for each release. A new folder should be added for each release where applicable.

This structure includes mandatory folders, which can remain empty if a product doesn't have certain document types. Create a subfolder for each release for documents unique to that release.

01_technical_overview_0401.png

Subfolders in technical documents structure​

  • 3rd-party and OSS: Manage third-party software-related artifacts during development and the product lifecycle. The 3rd-party software list is usually handled for each product release together with the project CM plan. For more details, please refer to the artifacts in 3rd-Party-and-OSS.

  • Architecture: Architecture is fundamental for system/product development. It's recommended that architecture descriptions are documented for each product release. For more information, refer to Architecture Document Structure and Versioning Architecture Documents.

  • Certifications: Archive product-related certificates throughout the product lifecycle. It's suggested to create subfolders for different standards and regulations to contain different certificates. Links can be used if certificates exist in a special location.

  • Document Management：Archive product-related documents used review checklists or dedicated templates.

  • Explosion Protection: Archive Explosion protection reports and test records. See Explosion Protection for related artifacts.

    01_Ex_templates.png

  • Functional Safety: See Safety Handbook - Artifacts for safety-related artifacts. Many safety-related artifacts can be handled together with other process areas, e.g., safety requirements, safety validation tests, etc. Here are some examples for safety used templates.

    01_FS_templates.png

  • Hardware Development: Create subfolders with hardware article numbers (type designation) to contain different folders for design, maintenance, manufacturing, and verification documents. Refer to Hardware Development and PLM for more information on artifacts and required location. Here are some examples of hardware used templates:

    01_HW_Templates.png

  • Intellectual Property: Archive documents related to product intellectual property. See Intellectual Property for more information.

    01_IP_templates.png

  • Requirements: Archive requirements-related information. Refer to Requirements

    01_requirements_templates.png

  • Software Development: Store software development artifacts. Related information should be formally controlled during the product lifecycle, see Software Development. If a specific tool is chosen for software development, it shall be documented and controlled by a 3rd-party software process. Below is an example of possible artifacts handled in "Software Development".

    01_sw_templates.png

  • Test: Store product-level test documents. Here's mainly for product-level tests. For more details, please refer to artifacts in Test. Currently, the ADO test plan is recommended for test cases and test results. Refer to How-to Create Test Plans and Test Suites and How to Write and Review a Test Case in ADO

    Under the Test folder, there shall be a subfolder for each type of product test.

    01_Test_level1.png

    01_Test_level2.png

    Under each folder where documents are unique for each product release, there shall be a subfolder for each release, e.g., for test records, as below.

    01_Test_Records_level2.png

    There's also an example of the templates that were used.

    01_test_templates.png

Projects documents structure​

The 02 Project Documents folder stores documents related to projects executed during a product's lifecycle. These documents are tied to the respective release project lifecycle. It's recommended that separate subfolders are created for each product release.

02_projects_overview.png

Under each release, there are four subfolders as below:

  • Document Management
  • Gate and Milestone Checklists
  • Gate and Steco Report
  • Integrated Project Management

Document Management​

The document management related artifact could be here, e.g. review checklist and review record for project.

02_document_templates.png

Integrated Project Management​

This subfolder could contain administrative documents, such as the project description & plan, quality plan, and CM plan. For more information, refer to the artifacts in PCP OnePoint: Integrated-Project-Management.

02_IPM_overview.png

  • Configuration Management: Project CM-related artifacts can be stored here. Here's an example.

    02_project_level4_CM.png

  • Cyber Security: The templates below are intended for every release. For more information, refer to the Cyber Security process page and guidelines for Security Assessment.

    02_project_level4_cyber.png

  • Quality: Quality plan and quality reports are stored here for each release.

    03_quality_template.png

  • Test Plan: The project's test strategy and plan is stored here together with its related checklist.

Gate and Milestone Checklists​

Archive gates/milestones checklists to align with the ABB Gate Model. Refer to PMO for more information.

02_gate_checklist.png

Gate and SteCo Report​

Archive reports for applicable gates or milestones and regular SteCO reports.

01_gate_reports.png

Product Life Cycle Structure​

The 03 Product Life Cycle folder stores documents related to product management from the R&D side. It could be product management, product maintenance, or product configuration management related. It's suggested to create separate subfolders for respective product or system versions. Here are examples:

03_product_overview.png

03_product_level2o.png

  • Configuration Management: Project baselines of deliverables mapping to each release. Here's an example:

    03_product_CM.png

  • L4 and Maintenance: Store R&D documents for product maintenance. Refer to L4-and-Maintenance for more details.

    03_product_L4_templates.png

  • Product Management: R&D documents and artifacts for product management. Here's an example:

    03_product_maangement.png

    There is sepreate section for Products and Systems in DMS, which is different area from ATPA. Our Product Managers manage product and portoflio documents there. while systerm release owners and configuration managers handle system integration and maintenance related documents. These are outside the scope of this guideline.

    03_products_systems.png

The 04 Process Related Guidelines folder is optional. Usually, it's recommended to use the project's quality plan to document process deviations. If guidelines or work instructions are specific to a particular product line or site, they can be archived in this folder. Alternatively, these documents/artifacts can also be stored in the relevant process area folder within the 01 folder.

For clarity and consistency, it's important to ensure that all documents stored in this folder or elsewhere are properly versioned and reviewed according to relevant quality standards.

How to implement the proposed structure​

To assist users in adopting the proposed structure efficiently, the PMO is leading one continuously improvement project - Cockpit, DMS team is developing an automated tool to deploy the folder structure whenever a new release is submitted for establishment in DMS. This tool will not only deploy the selected structures together, but also include applicaple templates links under each subfolder, similar shown as .dmsftc in above 01，02，03 folders. Additionally, a team project with same functions to DMS will be created for internal communication and sychronization. The newly created DMS structure will also be linked to this team project. Further details will be published in the PCP BMS PMO area.

Currently, the folder structure needs to be created manually in DMS. For help, please contact your quality control manager, configuration manager, or power-user.

References​

Owner: DMS Team