Use Case: Document Tracking
Whether you are tracking work products for an ISO 26262 safety plan, process steps for ASPICE, or compliance with any other quality management system, TraceForge™ can track your documents through your development lifecycle.
Consider the following scenario:
- Your project has a list of required work products. A “work product” is a set of information that satisfies some project or regulatory need, such as requirements, test evidence, design information, etc.
- A single document (file) might fulfill the objectives for multiple work products. Some work product objectives might need multiple documents (files) to be complete.
- Each work product typically needs some sort of verification record, such as a review.
TraceForge™ lets you manage this scenario with ease with the following workflow.
1. Define your element types and relationships
A plain-text description of the goal of our document management project might be “We want to specify a list of required work product roles. Then we want to track which file(s) satisfy those roles as well as track that each file is verified against the requirements for its role.”
We want to make our documents easy to read, so we want to give document authors the ability to write naturally. We want to be able to easily define role IDs, document IDs, and review IDs and link them together. When we create an entry in our role list, we might want to write “role[role-id]”. When we create a document that fulfills a role, we might want to write “doc[doc-id] fulfills[role-id]”. When we have a document that records the evidence of a review of a document against its roles, we might want to write “review[review-id] of[doc-id] against[role-id]”.
So our TraceForge™ configuration will define three tag types and the expected relationships between them.
▶ Document Role
Tags of this type identify a required work product role in your project plan. They don’t have a parent, and we expect to have a document claiming to satisfy each required document. Since we want to review the document against the role, we also say that each document role must have a record of its review.
type docrole format:"\\[docrole\\-[[:alnum:]]+\\]" root allof [document review]▶ Document
Tags of this type identify the documents themselves. These elements should have a parent (the document role) and each document should also have a review.
type document format:"\\[doc\\-[[:alnum:]]+\\]" allof [review]▶ Review Record
Tags of this type identify a file that contains the evidence of review. Since a review has no child documents, this type is marked as leaf.
type review format:"\\[review\\-[[:alnum:]]+\\]" leaf▶ Definition and Link prefixes
Setting up the definition and link prefixes to let us write natural language is straightforward:
def "role"
def "doc"
def "review"
lnk "fulfills"
lnk "of"
lnk "against"2. Create the Role List
Our project definitely has one known file: the document containing the list of roles we need. When we create this file and create tags that match the Document Role tag type, we create the first link our traceability chain.
This might be an Excel spreadsheet, a table in a Pages document, a Project Plan, or even plain-text. This list can even span multiple files! For our example let’s say it’s in an Excel spreadsheet. Since Excel spreadsheets cannot be read natively by TraceForge™ we must specify a tool or script to first convert the file.
file "projplan.xlsx" convert:"xlsx-to-csv"3. Use TraceForge™ during the project
As our team makes progress on the project, they will create documents and place them in our file system according to company standards. The project manager and team members can all periodically run TraceForge™ to generate reports that indicate both the status and progress of the project, as well as identify what steps might need to be taken next.
traceforge -c project-config.txt -o project-report.tfrpt project-directory/*.*▶ First Run
The first time we run TraceForge™ we see the project plan document was scanned and that each of the 5 document roles we defined are missing a document and a review.
▶ Track Project Status
TraceForge™ will show progress as the project team creates documents to satisfy the defined roles. Give your team a clear picture of the status of the project: see how many tags have their required prerequisites, the relationships between documents and relationships between roles, which documents still need to be written and/or reviewed, and any other issues in the document relationships.
- Summary of tags that have all their constraints fulfilled
- View map of relationships between files
- View graph of relationships between document roles and reviews
- Identify any other issues with the documents
- Track which documents and roles are missing
