Artefact Fields
Within ArchRepo, Artefacts are defined with a small set of fields that identify the document, classify it, record its version, and link to where it is stored.
1. Description
-
What it’s for: A plain-language summary of what this artefact is and why it was produced.
-
What to include:
- Describe the document’s purpose and what it covers.
- Include the intended audience if that is not obvious from the name.
- Keep it brief — one or two sentences is usually sufficient.
-
Example:
"The Solution Design Document describes the technical architecture for the customer portal integration, including API contracts, data flows, and deployment topology. Intended for the technical delivery team and solution assurance reviewers."
2. Link to Artefact
-
What it’s for: A direct URL to the artefact in the system where it is stored.
-
What to include:
- Provide a link that will take the reader directly to the document — not just a folder or home page.
- Common storage locations: SharePoint, Confluence, Google Drive, a document management system, a Git repository.
- If the document requires access permissions, note that in the Description rather than omitting the link.
-
Example:
https://contoso.sharepoint.com/sites/ProjectX/Documents/SDD-v1.2.docx
3. Type
- What it’s for: Classifies the artefact within the project’s document landscape, making it easy to filter and find related documents.
- Options:
| Type | When to use |
|---|---|
| Commercial | Contracts, statements of work, purchase orders, vendor agreements, commercial schedules |
| Project | Project plans, status reports, meeting minutes, RAID logs, governance documents |
| Solution | Solution designs, architecture decision records, integration specifications, system overviews |
| Business | Business cases, stakeholder briefs, process documentation, operating model documents, training materials |
| Technical | Technical specifications, API documentation, infrastructure runbooks, deployment guides, configuration standards |
| Data | Data dictionaries, data mapping documents, data migration plans, data quality reports |
| Support | Support guides, operational procedures, handover documentation, incident runbooks |
| Other | Any deliverable that does not fit the above categories |
4. Artefact Version
-
What it’s for: Records the version number of this specific issue of the document.
-
What to include:
- Use whatever versioning convention the project applies — typically a simple numeric scheme such as
1.0,1.1,2.0, or a draft notation such as0.1,DRAFT. - Create a new Artefact record for each new version rather than updating the existing one. This preserves a history of what was in place at each point in the project.
- Use whatever versioning convention the project applies — typically a simple numeric scheme such as
-
Example:
2.1
5. Date Issued
- What it’s for: The date on which this version of the artefact was formally issued, published, or shared with its intended audience.
- What to include:
- Use the date the document was approved and circulated — not the date it was drafted or last edited.
- For documents that go through a formal review and sign-off process, this is typically the date it was marked as approved or released.