03_version_control_for_documents

Version Control for Documents

While Git is our standard for code, managing versions of non-code documents (like project briefs, designs, and client-facing documents) also requires a clear process.

Preferred Tools

• Google Workspace (Docs, Sheets, Slides): This is our preferred tool for collaborative documents. Its built-in version history and commenting features are excellent for tracking changes and providing feedback.
• Confluence: For our internal knowledge base, Confluence has its own versioning system.
• Figma/Sketch: For design files, these tools have their own versioning and collaboration features.

Naming Conventions for Versions

When you need to create a distinct version of a document (e.g., for a client deliverable), use a clear versioning scheme in the file name.

• Major Versions (v1, v2): Use for significant changes or milestones (e.g., project-brief_v1.docx, project-brief_v2.docx).
• Minor Versions (v1.1, v1.2): Use for smaller revisions or updates.
• Status: You can also include a status in the file name, such as _draft, _review, or _final.

Example:

• acme-project-proposal_v1.0_draft.docx
• acme-project-proposal_v1.1_review.docx
• acme-project-proposal_v1.2_final.docx

Using Google Drive/Workspace

• Master Document: Always have a single “master” document that is the source of truth. Avoid creating multiple copies of the same file.
• Version History: To see the history of a Google Doc, go to File > Version history > See version history. You can name specific versions to mark important milestones.
• Suggesting Mode: When making changes to a document that others need to review, use “Suggesting” mode. This is similar to a pull request for documents.
• Sharing: Use shared drives for all project-related documents to ensure the team has access.

When to Use Git for Documents

In some cases, it may be appropriate to use Git for documentation, especially for technical documentation that lives close to the code.

• Markdown Files: Project README.md files, architectural decision records (ADRs), and other developer-focused documentation written in Markdown should be stored in the project’s Git repository.
• Benefits:
  • Changes can be reviewed via pull requests, following our standard Git Workflow.
  • The documentation stays in sync with the code it describes.

Archiving Old Versions

• Once a document is final and a new major version is created, you can move the old version to an _archive folder to keep the main directory clean.
• Do not delete old versions unless you are certain they are no longer needed for legal or compliance reasons.