References in Process Artifacts

References between artifacts (e.g., documents and web pages) support the user to find more information easily. It also ensures the same content isn't repeated in several places and can therefore simplify maintenance. But wrongly used, with too many references, the contents can be hard to read for the user and become costly to maintain.

note

Try to minimize the references in process artifacts. With modern tools, many references can be replaced with a search function to find the information needed.

One way of minimizing the number of references is to define what artifacts are allowed to reference other artifacts. E.g., a policy shouldn't have any references - it should be self-contained. A process description can have many internal references to other documents but should have few external references.

The picture below shows the process description that mainly references other sources and serves as the starting point for the user to find information.

Recommendations to minimize the number of references

• Do not reference documents that are easy to find or search for (e.g., terminology, role descriptions, and governance)
• Check the references are used in the contents (avoid "good-to-have" references)
• Avoid double-directed references, i.e., references to a document and back

Internal References

If the references are contained within PCP ONEPOINT (including PCP R&D Processes) - then they are internal. PCP controls the referenced artifacts and can decide about updates.

Artifacts referenced within PCP R&D Processes

• Use references within R&D's processes to help the user to find information
• Use clickable links if possible to go to the information directly

Artifacts referenced within PCP ONEPOINT (non-R&D)

• Restrict references to other organizational functions (e.g., PPM, Operations, and Manufacturing) artifacts since we don't always know when they are updated.

External References

External references are those artifacts PCP doesn't control. They can be updated at any time without notice. We frequently need to check for updates and make corresponding updates.

The web portal creates a list of external references (URLs) for each page. Use it to check external links and see if they are needed or not.

Artifacts within ABB (non-PCP)

• Restrict references to normative ABB documents if possible
• Reference a specific version of an ABB artifact (i.e., we can decide when to update our references)
• Use artifacts to collect sets of informative references, e.g., a page with recommended ABB MyLearning courses

Artifacts outside ABB

• Restrict references to external sources for policies and process descriptions
• Guides can have external references to explain details (avoid "copy/paste" information into the guide)
• Use a reference to a specific version of an external artifact

Normative or informative references

References can be normative (mandatory - must be understood and followed) or informative (clarification or recommendation). The type of reference depends on how the reference is used (and not the content of the referenced document). A policy can be normative (we must fulfill activities the policy requires), but over time when we have included the activities in our processes - we don't need the policy anymore (except for checking changes).

warning

External normative references should be avoided (or at least minimized). PCP has to fulfill the external normative references, but PCP doesn't control the changes in the referenced documents.

Examples

• "A Safety case shall be developed as described in IEC 61508" (normative)
• "Story point shall be calculated as described in SAFe" (normative)
• "The principles for a safety assessment include: a) b) c). For further details, see 61508" (informative)
• "Increment planning uses the following agenda: x) y) z). The agenda is based on SAFe's PI-planning" (informative)

Broken references

Broken references (references to non-existing documents or invalid web pages) can occur due to many reasons. E.g., an artifact (document or web page) has changed its name or identity, or it has been moved or removed. A broken reference is easy to miss, and it's a reason to reduce the number of references.

The web portal validates external links used in pages and creates a list of the broken links to be corrected.

Documenting references in process artifacts

In the text, include a reference and link, e.g:
The details of the epic state transitions are described in the Work Item State Description.

Then in the end, in the reference section, summarize references made in the document, like:

References

• Work Item State Description

Details on how to link and capitalize are described in the Style Guide

note

Don't add references to guides or pages just because it is related – it must have a reference in the text.

Q&A

Why do we need to minimize references?

References in documents and links on web pages always need to be checked if they are valid or not. E.g., when a document is removed, other documents referencing it need to be updated as well. It can be extensive work to maintain references manually.

Links in web pages are easier to manage. It is possible to automatically validate a link and check if the page still exists. As soon as a link is not valid, the author can be warned about the broken links.

What differs between internal and external references?

Internal references point to documents or web pages controlled by the PCP organization. PCP does not control the external reference content.

External links (starting with "http:" or "https:") on a web page are indicated with the symbol after the reference. For documents - external references can be indicated in other ways (e.g., by the document number).

Let the URLs to documents in a document management system point to the "latest approved" - it lowers the need to update the URLs frequently.

Why do we need to know if a reference is normative or informative?

It is the external normative references we need to handle with care since we must ensure we fulfill them. The normative references depend on how we use them (textually) and not only on the contents of the referenced artifact. E.g., "use the bug classification described in IEC 62443 for security bugs" (normative) is different from "the code reviews for security are based on IEC 62443" (informative).

note

The difference between external and internal references is primarily important for the author to have in mind when formulating the reference. The actual reference documentation shall look the same.